RimWorld Wiki - User contributions [en]

Human meat

2026-03-26T20:48:53Z

Aelanna: Gorehulks drop twisted meat, not human meat.

{{See also|Meat (disambiguation)|Meat|Insect meat}}
{{Infobox main|food
| name = Human meat
| image = Meat human c.png
| description = Raw butchered flesh. Can be cooked into meals or eaten raw, although most humans dislike the idea.

| type = Food
| type2 = Raw food
| hp = 60
| deterioration = 6
| marketvalue = 0.8
| beauty = -4
| mass base = 0.03
| flammability = 0.5

| taste = Raw
| food poison chance = 0.02
| days to rot = 2
| nutrition = 0.05

| production facility 1 = Butcher spot
| production facility 2 = Butcher table
| work to make = 450
| work speed stat = Butchery Speed
}}
'''Human meat''' is [[meat]] obtained when a [[Work#Cook|cook]] butchers [[human]]s.

== Acquisition ==
Human meat is obtained when a [[Work#Cook|cook]] butchers [[human]]s. The base [[Meat Amount|Meat Yield]] are described on the table below but the actual number depends on the [[Butchery Efficiency]] of the butcher, damage of the corpse, and a number of other factors.

<div><li style="display: inline-table;">
{| {{STDT| sortable c_06 text-center}}
! Animal !! Meat Yield
|-
{{#ask: [[Meat Name::{{PAGENAME}}]] [[:+]]
| ?Meat Yield
| format = template
| template = Ask Table Formatter
| limit = 500
| link = none
| sort= From DLC, name}}
|}</li></div>

Without the [[Ideology DLC]], butchering a human gives {{--|6}} [[mood]] for all colonists in the colony, and an additional {{--|6}} to the butcher. The former moodlet does not stack, meaning butchering 100 corpses gives the same colony-wide mood as one (the butcher's penalty ''does'' stack). [[Psychopath]]s and pawns with [[bloodlust]] ignore either butchering penalty, as do any [[cannibal]]s.

The mood effects of butchering humans with an [[Ideoligion]]{{IdeologyIcon}} are based on the precept of the ideoligion the pawn follows.

== Usage ==
{{Ingredient List|noCollapse=true}}

== Summary ==
As a [[raw food]], human meat can be be eaten raw, with a flat {{Bad|2%}} chance of giving [[food poisoning]], or cooked into a [[meal]] with a food poisoning chance dependent on the skill of the cook and the [[cleanliness]] of the kitchen. [[Animals]] are immune to food poisoning from raw food but not from meals. When used in food recipes that require specific types of [[nutrition]], such as [[fine meal]]s, human meat are classified as meat.

Human meat is like any other [[raw food]]. It can be used to create [[meal]]s, or combined with other ingredients to produce fine, lavish meals, pemmican and kibble.

Most humans despise eating human meat, which is cannibalism. Raw human meat gives {{Thought|value=-20|stack=1|label=raw cannibalism|desc=I ate the meat of another human, raw, like an animal. This is a nightmare.|duration=1}}, and cooking human meat into [[meal]]s (including in [[nutrient paste meal|nutrient paste]]) gives {{Thought|value=-15|stack=1|label=cooked cannibalism|desc=I ate a meal made from the meat of another human. This is horrible.|duration=1}}. Pawns with the [[Cannibal (Trait)|Cannibal]] trait instead gain {{Thought|value=+20|stack=1|label=raw cannibalism|desc=I ate the meat of another human, raw, like an animal. It was so... succulent.|duration=1}} for raw human meat and {{Thought|value=+15|stack=1|label=cooked cannibalism|desc=I ate a meal made from the meat of another human. So pleasurable. If only I had some fava beans and a nice chianti.|duration=1}} for cooked human meat. The moodlets for raw and cooked cannibalism stack with each other, as do any moodlets from meal types.

Depending on the [[Ideoligion#Cannibalism|canibalism precept]] {{IdeologyIcon}} colonists gain instead:
* Cannibalism abhorrent: {{Thought|value=-20|stack=1|label=ate human meat|desc=I had to eat human meat. This is an offense against everything I believe.|duration=1}}
* Cannibalism horrible: {{Thought|value=-12|stack=1|label=ate human meat|desc=I had to eat human meat. This was a horrible thing.|duration=1}}
* Cannibalism dissapproved: {{Thought|value=-5|stack=1|label=ate human meat|desc=I had to eat human meat. I believe such actions are wrong.|duration=1}}
* Cannibalism acceptable: ''none''
* Cannibalism preferred: {{Thought|value=+2|stack=1|label=ate human meat|desc=I ate human meat. It makes me feel noble and strong.|duration=1}}
* Cannibalism required (strong): {{Thought|value=+4|stack=1|label=ate human meat|desc=I ate human meat, as every real human should.|duration=1}}
* Cannibalism required (ravenous): {{Thought|value=+6|stack=1|label=ate human meat|desc=I ate human meat! The world is right, and I am as I should be.|duration=1}}

Processing human meat, once it has been butchered, incurs no penalties. Human meat can be made into meals, used for animal feed, processed in [[biofuel refinery]] for [[chemfuel]], or put in a [[biosculpter pod]]{{IdeologyIcon}} or [[growth vat]]{{BiotechIcon}}, and nobody will feel bad about it unless it is eaten directly.

When consumed by [[Hemogenic]]{{BiotechIcon}} pawns, human meat satisfies the [[Hemogen]]{{BiotechIcon}} need by {{+|3.75}} per 1 [[nutrition]], or {{Icon Small|Human meat||{{#expr:1/{{P|Nutrition}}}}}}, consumed.{{Check Tag|Rounding?|This rounds to +4 for 20 meat, exact rounding mechanics needed}}. Note that only the raw meat provides this hemogen, eating [[corpse]]s or the meat cooked into [[meals]] does not.

Its market value is only {{Icon Small|silver||{{P|Market Value Base}}}} [[silver]], or {{%|{{P|Market Value Base}}/{{Q|Meat|Market Value Base}}|0}} of regular meat. However, processing it into meals or [[chemfuel]] will ignore its origin when considering market value.

Human meat is also used as a building ingredient for the [[cannibal platter]]{{IdeologyIcon}}, which requires {{Required Resources|Cannibal platter|simple=1}}.

== Analysis ==
Butchering a human is already upsetting for a good majority of colonists. So in a colony not filled with cannibals, eating it should only be for absolute emergencies, in extreme [[biome]]s like sea ice, or to please a cannibal on verge of [[mental break]]. For a cannibal, both the cooked cannibalism and raw cannibalism mood buffs stack, for a total of {{+|35}} mood. However, most cannibals still get {{Thought|value=-7|stack=1|label=ate raw food|desc=I had to eat raw food. We should be cooking that kind of food before eating it. We're not animals.|duration=1}}. You can further boost mood with [[fine meal]]s, [[lavish meal]]s, or their [[carnivore fine meal|carnivore]] [[carnivore lavish meal|variant]]s. Alternatively, the massive mood debuff might make human meat situationally useful. It may force a [[tortured artist]] into a mental break, or cause a [[Crisis of belief]] in the [[Ideology DLC]]. As for [[Caravan]]s and Raiding, Human Meat is one of the most abundant food sources that can be acquired while on-site by butchering several of the corpses found from the pawns killed and in [[Gibbet cage]]s {{IdeologyIcon}}, cooking them into Meals for slower spoilage.

Using human meat for carnivorous animals (whenever raw or [[kibble]]) isn't cannibalism, so the animals won't mind. It may be wiser to leave corpses unbutchered, as the butchering itself has a fairly large penalty to both the butcher and the colony. Note that colonists in base game or with the [[Ideoligion#Corpses|Corpses ugly]] precept {{IdeologyIcon}} will get {{--|4}} mood from observing them.

In the [[Ideology DLC]], a colony's [[ideoligion]] can make this a different story. With the Cannibalism meme and/or precept, [[raider]]s become a completely viable source of both food and positive moodlets. Setting the precept to Required (Ravenous) gives the greatest mood buffs, +6 per meal, but also gives a strong debuff when human meat isn't available. This is also possible in the base game, with a colony entirely composed of the cannibal trait. By adjusting the [[scenario]] ("Forced trait"), you can set all starting colonists, or every pawn in the game, to be cannibals.

== Gallery ==
<gallery>
Meat human a.png|One human meat
Meat human b.png|Partial stack
Meat human c.png|Full stack
</gallery>

== Version history ==
<gallery>
Meat human old.png|Old texture
</gallery>

{{Nav|Food|wide}}
[[Category:Food]] [[Category:Raw Food]] [[Category:Meat]]

Legionary

2026-03-14T20:50:56Z

Aelanna: Cleaning up added section.

{{Biotech}}
{{See also|Centurion}}
{{infobox main|none|
| name = Legionary
| image = LegionaryAncient east.png
| description = A combat support mechanoid with a wide-range bullet shield and mid-range needle gun. Designed to support other mechanoids, the legionary is vulnerable to anyone who can get inside its shield.
| combatPower = 150
| type = Mechanoid
| movespeed = 4.3
| flammability = 0
| marketvalue = 1200
| armorblunt = 20
| armorsharp = 40
| armorheat = 200
| min comfortable temperature = -100
| max comfortable temperature = 250
| psychic sensitivity = 0.5
| toxic resistance = 1
| toxic environment resistance = 1
| bandwidth cost = 2
| bodysize = 1
| healthscale = 0.72
| lifespan =
| attack1dmg = 12
| attack1type = Blunt
| attack1cool = 2
| attack1part = left fist
| attack2dmg = 12
| attack2type = Blunt
| attack2cool = 2
| attack2part = right fist
| attack3dmg = 8.5
| attack3type = Blunt
| attack3cool = 2
| attack3part = head
| attack3chancefactor = 0.2
| page verified for version = 1.4.3525
| weaponTags = MechanoidGunNeedleLauncher

| research = Ultra mechtech
| production facility 1 = Large mech gestator
| gestation cycles = 4
| resource 1 = Plasteel
| resource 1 amount = 100
| resource 2 = Component
| resource 2 amount = 6
| resource 3 = High subcore
| resource 3 amount = 1
}}
A '''legionary''' is a [[mechanoids|mechanoid]] added by the [[Biotech DLC]] that projects a shield.

== Acquisition ==
{{Acquisition}}

Dead, friendly {{lc:{{PAGENAME}}}}s can also be resurrected at the {{lc:{{P|Production Facility 1}}}} using the "''Resurrect medium mechanoid''" bill. This requires the corpse of the friendly {{PAGENAME}}, {{Icon Small|Steel||50}} [[steel]], and 1 [[gestation cycle]] taking {{ticks|1800}} to initiate.

== Summary ==
{{Mechanoid Summary}}

Dead legionaries may be shredded at the [[machining table]] or [[crafting spot]] for {{Icon Small|Steel||15}} [[steel]]. However, these values are affected by [[Mechanoid Shredding Efficiency|mechanoid shredding efficiency]], as well as missing parts on the legionary.

=== Shield ===
[[File:Legionary shield radius.png|thumb|left|175px|Radius of the legionary's shield with unshielded area denoted in red, partially shielded areas in gold (see Note right).<br> Note that despite the shield visually extends into the red tiles, it does not protect them.]]

The legionary projects a shield that is 3 tiles in radius, centered on the mech and moving with it, and which is visible whenever drafted or attacked. The shield stops all incoming enemy ground-level fire from passing into the bubble. It does not prevent pawns of any faction that are inside from firing out. Also note that this only applies to ground-level fire, i.e. fire from ranged [[weapons]] carried by all types of [[pawn]] and [[turrets]], including grenades that cross the boundary of the shield. Explosives projectiles will detonate on the shield edge. Fire from [[mortar]]s, [[orbital bombardment targeter|orbital bombardment]], or [[Titles#Permits|aerodrone strikes or salvos]] {{RoyaltyIcon}} will not be blocked by the shield, nor will explosions crossing the boundary.

'''Note:''' Pawns on the tiles shown in [[gold tile|gold]] in the image to the left are shielded from attacks directly targeted at them, however, due to a bug, they can still be hit by attacks aimed at other nearby pawns that miss.

The shield can absorb up to 200 damage before breaking. If an attack would be sufficient to completely deplete the shield's charge, then the rest of its damage is negated, and the shield is temporarily broken.  The shield regenerates charge at rate of 0.25 HP per second, so long as it has not been broken. However, once the shield's charge is completely expended, the shield will break and be totally disabled for {{ticks|5400}} after which point the shield will be restored at full health. Projectiles from [[EMP grenades]] and [[EMP launcher|launchers]] from outside hitting the shield will disable the shield for {{ticks|1500}}, after which time the shield will be restored at full health. Note that {{Hover title|Version/1.6.4630|as of the time of writing}}, projectiles [[unique weapons]] with the [[EMP rounds]]{{OdysseyIcon}} trait do not disable the shield when striking it. It is currently unknown whether this is intended or considered a bug. It is also currently unknown if striking the mechanoid itself disables the shield.{{Check Tag|Verify}} Furthermore, unlike the mechanoid itself, the shield projector will not adapt to the EMP effect. Its therefore possible to continuously disable the shield until the mechanoid can be killed. Note that an EMP area of effect overlapping with the projected shield will not disable it - a projectile must hit the shield or the EMP damage must be dealt to the structure itself

If the [[EMP]] damage is dealt to the legionary itself, the shield is similarly disabled for {{ticks|1500}}, but will continue to regenerate as if it was not.

A pawn does not need to be inside the shield to benefit from the effect, assuming the enemy is not inside the shield and that the shield is between them and their attacker the incoming rounds will be stopped. However, it does not prevent pawns from moving inside the shield and attacking.

=== As an ally ===
Mechs under player control require power: legionaries use 10% of their power per day while active. If set to dormant self-charging, they instead recharge for 1% power / day, without pollution. They recharge in a [[large mech recharger]] (400W), for 50% power/day, creating 10 [[wastepack]]s whenever the recharger's waste is filled up.

=== Combat ===
Legionaries are always equipped with a [[needle launcher]], which they do not drop upon death. See the [[needle launcher]] page for further information.

Legionaries have a [[shooting accuracy]] of 96%, equivalent to a pawn with a [[Shooting]] skill of 8. They have a [[melee hit chance]] of 62%, equivalent to a pawn with a [[Melee]] skill of 4.

== Analysis ==
{{Stub|section=1|reason=Needs at least comparison to Centurion for mechanitors choosing a shield mech, but also there's strategies for using the shield, distribution on a firing line, lillboz design, and moee esoteric like square packing legionaries and letting them go wild in a walled tile to make a shield wall etc}}
=== As an enemy ===
* The launcher is weak, but don't underestimate it. It's still strong enough to destroy vulnerable organs, including the brain.
* EMP works well to break the shield, if you can get close enough at all. Legionaries are often surrounded by powerful mechanoids due to their advanced nature.

===As an ally===
The Legionary's shield provides a safe space for your ranged pawns to attack the enemy without worrying about retaliatory fire. With 200 hitpoints, slow firing weapons like pila, sniper rifles, and charge lances will no longer trouble your pawns as their slow fire rate gives the shield a bit of time to regenerate. However, care should still be utilized when relying on its shield. Exposure to rapid-fire weapons like miniguns or heavy charge blasters (both found on Centipedes) can shred the shield extremely fast.

As a projected momentum repulsor field, the Legionary's shield is vulnerable to EMP, so try to take out enemies who wield EMP grenades or launchers first.

===Comparison===
When compared to [[centurion]]s, legionaries are cheaper to build as they do not require advanced components or powerfocus chips, only use 2 bandwidth instead of 5, but also have a smaller and weaker shield. When using a lot of higher-tier mechs such as [[centipede]]s it is more resource efficient to make one or two legionaries to defend them rather than a single centurion. However, a centurion provides higher shield coverage and lets you cram more mechs into the same shield.

== Health ==
=== Body parts ===
{{Animal Health Table|Lancer}}
=== Armor ===
{| class="wikitable"
! Armor
|-
| {{Apparel Protection Chart
| set1name= {{P|Name}} (Sharp) | set1armor1={{P|Armor - Sharp}}
| set2name= {{P|Name}} (Blunt) | set2armor1={{P|Armor - Blunt}}
| set3name= {{P|Name}} (Heat) | set3armor1={{P|Armor - Heat}}
| color= grey, blue, red
}}
|}
{{Pawn Attack Table|weapon=Needle launcher}}

== Trivia ==
Both shield mechanoids, the centurion and the legionary, are named after positions in the ancient Roman Army. The Roman Army famously used large shields called scuta.

== Gallery ==
<gallery>
Legionary east.png| Age 0-99 Legionary facing east
Legionary north.png| Age 0-99 Legionary facing north
Legionary south.png| Age 0-99 Legionary facing south
</gallery><gallery>
LegionaryAncient east.png| Age 100+ Legionary facing east
LegionaryAncient north.png| Age 100+ Legionary facing north
LegionaryAncient south.png| Age 100+ Legionary facing south
</gallery>

== Version history ==
* [[Biotech DLC]] Release - Added.
* [[Version/1.4.3555|1.4.3555]] - Weapon changed from needle gun to needle launcher.
* ? - Description changed to reflect change from needle gun to needle launcher. ''A combat support mechanoid with a wide range bullet shield and long-range needle gun. Designed to support other mechanoids from long range, the legionary is vulnerable to anyone who can get inside its shield.'' -> ''A combat support mechanoid with a wide-range bullet shield and mid-range needle gun. Designed to support other mechanoids, the legionary is vulnerable to anyone who can get inside its shield''
* [[Version/1.4.3682|1.4.3682]] - Fix: Missing final period in legionary description.

{{nav|mechanoid|wide}}
[[Category:Mechanoids]]

Psychic soothe pulser

2026-03-12T15:19:54Z

Aelanna: /* Summary */

{{infobox main|
| name = Psychic soothe pulser
| image = Psychic_soothe_pulser.png|Psychic soothe pulser
| description = A one-use broad-wave psychic effector. The psychic pulse induces self-satisfying perceptual distortions, giving a temporary mood boost to everyone in the region.
| type = Artifact
| tech level = Archotech
| marketvalue = 600
| hp = 80
| flammability = 0
| mass base = 0.5
| page verified for version = 1.3.3326
| thingSetMakerTags = RewardStandardHighFreq
}}
{{Info|A '''psychic soothe pulser''' is a single-use [[artifact]] which gives a "Strange feeling" thought with a +15 [[mood]] buff and 24 hour duration to every colonist on the map when activated.}}

== Acquisition ==
Psychic soothe pulsers cannot be crafted. Instead they can only be obtained through [[trade]] with [[faction base]]s or exotic goods traders, as a reward from [[quests]], or by finding them in [[ancient shrine]]s.

== Summary ==
A psychic soothe pulser is a single-use artifact that can be activated by selecting a colonist, right-clicking the artifact, and selecting 'Activate'

The pulser gives the "''Strange feeling''" thought with a {{+|15}} [[mood]] buff to every [[human]] pawn on the map upon activation, including prisoners and raiders. The size of the mood bonus is scaled directly proportionally to each pawn's [[Psychic Sensitivity]] - a [[Psychically hypersensitive|hypersensitive pawn]] will receive a {{+|27}} while a [[psychically deaf]] pawn will receive no buff at all. If the psychic sensitivity of the pawn changes while the thought is still present, the mood buff will change with it.

The psychic soothe pulser's bonus can be stacked up to 3 times. The second pulse will add an additional {{+|11}} before psychic sensitivity effects, and the third will add {{+|9}}, for a total mood bonus of {{+|35}}.

The mood buff lasts for 24 hours. Note that pawns entering the map after activation are not affected, nor are pawns in [[cryptosleep casket]]s.

Once it has been used once, the pulser disappears completely. It cannot be reloaded, nor can any resources be salvaged from it.

== Analysis ==
Psychic soothe pulsers are useful for any situation where a large number of colonists are suffering, or are likely to suffer, from a poor mood. Perhaps the most common example is long late-game raids, where colonists are deprived of [[rest]], [[saturation|food]], and [[recreation]], in addition to seeing [[corpse]]s or [[death]] - even of loved ones. Pulsers can keep pawns from [[mental break|breaking]] at inopportune times; mental breaks are dangerous for the pawn, and at the very least leaves the colony with 1 less defender.

Psychic soothe pulsers can be also be used to counteract [[psychic drone]]s. A single pulser can completely nullify the effects of a low psychic drone and still have a {{+|3}} net effect on mood. Higher levels of drone will be reduced in intensity as well. Whilst doing so is expensive, it's possible to turn an extreme psychic drone's {{--|40}} effect on mood into a paltry {{--|5}} by activating 3 pulsers at the same time for the maximum soothe effect. By the time a colony is being affected by such extreme psychic events, it is likely in a position where it can afford to purchase multiple pulsers in preparation for such events.

If possible, gather/save a few soothe pulsers for the [[ship launch]] or [[endings#Royal Ascent|royal ascent]]{{RoyaltyIcon}} [[endings]]. Not only are back-to-back raids quickly damaging to mood, but pawns often need to work to repair defenses when their needs are at their lowest.

== Lore ==
Psychic effectors, like the psychic soothe pulser, are mentioned in the [[Lore#Specific_archotech-invented_technologies|Lore Primer]]. They are described as archotech in origin, with a completely unknown method of operation.

== Version history ==
* [[Version/0.12.906|0.12.906]] - Added
* 1.1 - received new visual and sound effects on use.

[[Category:Artifact]]

Muscle parasites

2026-03-12T15:03:45Z

Aelanna: The math was correct. Cleaning the sentence structure while I'm in here.

'''Muscle parasites''' are a parasitic [[disease]] hampering the muscles, decreasing their effectiveness. The disease does not kill the patient.

== Effects ==
* [[Pain]]: {{++|20%}}
* [[Sleep Fall Rate]]: {{++|100%}}
* [[Manipulation]]: {{--|30%}}
* [[Moving]]: {{--|30%}}

== Progression ==
Muscle parasites do not increase in severity over time, nor are they cured over time. Direct treatment is the primary way to cure it.

== Treatment ==
Muscle parasites will be cured when the tending performed on it reach a cumulative tend quality of 300%, thus it is important to maximize the [[medical tend quality]] of the doctor performing the treatment and the quality of the medicine used. Treatment can only be performed every 48 ingame hours (2 days, {{Ticks|120000}}).

For example, the disease can be treated with 3 tends at 100% quality, 5 tends at 60%, or 1 tend at 130% quality plus 2 tends at 85%.

=== Other Treatments ===
* Administer [[healer mech serum]] which instantly treats the disease
* Use the medic cycle of the [[Biosculpter pod]] {{IdeologyIcon}}

== Prevention ==
The [[perfect immunity]] gene{{BiotechIcon}} will prevent the acquisition of this disease but will not cure pre-existing conditions present at the time of implantation.

== Trivia ==
In real life, humans can become infected by eating infected pork, or wild carnivores such as fox, cat, or bear.

Unlike in-game, muscle parasites can kill in real life.

== Version history ==
Prior to Beta 19, muscle parasites always required 5 treatments regardless of quality.

{{Nav|disease|wide}}
[[Category:Disease]]

Piloting Ability

2026-03-12T14:58:29Z

Aelanna: Moving added text outside of base stat description, which matches the in-game <description>.

{{Odyssey}}
{{Stub|reason=1) How it translates to grav ship outcomes 2) passenger shuttle? 3) Interlinking}}
{{Verified|1.6.4523}}{{Stat
| default base value = 1
| to string style = PercentZero
| description = How well this person can pilot a vehicle.
| category = PawnWork
}}

A colonist's Piloting Ability determines the likelihood of a negative landing outcome when moving a [[gravship]]. It is disabled for colonists incapable of [[intellectual]].

== Stat Factors ==

=== Base Score ===
* [[Intellectual]][[Skill::Intellectual| ]]: [[Skill Base Factor::0.2|20%]] plus [[Skill Bonus Factor::0.075|7.5%]] per skill level

=== Capacities ===
* [[Consciousness]]: [[Consciousness Importance::1|100%]] importance, [[Consciousness Limit::-|No]] max
* [[Sight]]: [[Sight Importance::0.5|50%]] importance, [[Sight Limit::1|100%]] max
* [[Manipulation]]: [[Manipulation Importance::0.5|50%]] importance, [[Manipulation Limit::1|100%]] max

=== Offsets ===
* [[Pilot assistant]]: {{+|45%}}
{{Stat Factors Table}}

{{nav|stats|wide}}

Prisoner

2026-03-10T01:02:15Z

Aelanna: Slight edit as restraints are a multiplier, not a cap.

{| align=center
| {{Characters_Nav}}
|}
----

<onlyinclude>
{{imagemargin|[[File:prisoner_preview.png|right]]|18px}}'''Prisoners''' are [[people]] who have been taken captive. This usually includes [[raiders]], but colonists can be imprisoned too.{{TOCright}}</onlyinclude>

== Summary ==
Prisoners are ordinary pawns under restraint. They have no [[Recreation]] needs, but all other needs and most [[mood]]lets apply to them. This includes a need for [[food]] and the chance for [[mental break]]s. They are confined to their cell and will not do work. Prisoners retain their faction allegiance; imprisoned colonists who are released will immediately rejoin the colony, while other prisoners will try and leave the map. Prisoner restraints reduce their [[move speed]] by 65%.

Prisoners cannot open doors if not undergoing a [[#Prison Break|prison break]]. While inside your colony, they will try to leave if there is an opening, such as a hole in the wall or a held open door, including if it is held open because of an item inside. A prisoner that can move will wear the most comfortable{{Check Tag|Verify/Detail}} clothing placed in their cell. They eat the food with the best mood buff that they can reach, ignoring food restrictions. Mobile prisoners can use a [[nutrient paste dispenser]] that faces into their prison. Otherwise, wardens will bring any food allowed by their [[Food restriction|food restrictions]]. A prisoner's medical settings, as well as defaults for all prisoners, can be adjusted in their Health tab.

Colonists assigned to Warden can interact with a prisoner in multiple different ways, including delivering food and recruitment. Colonists assigned to either Warden or Doctoring can feed a prisoner in medical rest. See [[#Interaction]] for more details.

=== Unwaveringly loyal ===
Unwaveringly loyal prisoners are unable to be recruited to your colony, and do not have resistance to lower. They are otherwise the same as regular prisoners, including the ability to become a [[slave]]{{IdeologyIcon}}. Unwaveringly loyal pawns without a faction will be described as "not recruitable".

Unwaveringly loyal prisoners can be recruited after undergoing the [[Brainwipe]] psychic ritual.{{AnomalyIcon}} Additionally, if an unwaveringly loyal pawn joins your colony through any means, they will lose their unwavering loyalty. Thus, unwaveringly loyal pawns from a temporary faction (such as the [[Factions#Refugees|refugee faction]] {{RoyaltyIcon}}) or [[Factions#Factionless_humans|no faction]] can be recruited by [[Slavery|enslaving]] {{IdeologyIcon}} them, which makes them a member of the player's faction, and then emancipating them, which makes them a normal member of the player's colony. Friendly [[shamblers]] {{AnomalyIcon}} also automatically join the player's faction, which will remove the unwavering loyalty of a prisoner, though they will have to brought back to life with a [[resurrector mech serum]] to be recruited as a normal colonist.

Unwavering loyalty can be disabled in the [[storyteller settings]]. Note that the enabling unwaveringly loyal pawns decreases the percentage of raiders that are automatically killed on [[down]]ing to almost exactly make up for the percentage of pawns that are now unrecruitable - this means that the number of recruitable prisoners remains constant with either option, but the total number of prisoners increases with unwaveringly loyal enabled. This is pure benefit if the player only intends to recruit from the pool of randomly downed raiders, however if the player was willing to specifically target good pawns for safe-downing and recruitment, such as through [[blood loss|bleed]] kiting or [[psychic shock lance]], then some portion of those previously recruitable pawns will instead be loyal and thus unavailable.

=== Caravans ===
Prisoners can be loaded into a [[caravan]]. If they can walk, they can carry 35 kg worth of items, like your colonists. When inside a caravan, the prisoner will never try and escape unless its part of a [[mental break]].

If the caravan enters a loaded map (such as an ambush), the prisoner will wander around idly, and may walk into the crossfire. Enemies will also target prisoners if their factions are enemies.

== Capturing prisoners ==
In order to capture any prisoner, you need a valid prison, which is enclosed and has an open [[bed]] or [[sleeping spot]] (See [[#Prisons]] below).

The gameplay steps required to capture a pawn depends on their state:
* [[Downed]] pawns can be captured with 100% success, without drafting a pawn. Select a colonist, and right click the future prisoner.
** [[Raider]]s, [[berserk]] pawns, and former prisoners in a [[prison break]] are unable to be captured directly. They must first be [[downed]].
** NOTE: Raiders in particular have a [[AI Storytellers#Enemy death on downed|chance to die]] whenever they are downed from [[pain]] - such as from being injured. This does not apply if the pawn is downed from other causes; some ways to get around this include:
*** [[Psychic shock lance]], although there is a risk of burning the brain
*** [[Blood loss]]
*** [[Tox gas]]{{BiotechIcon}}, although not all xenotypes are affected, and [[Toxic buildup]] also has risks
* To ''arrest'' a colonist, guest, ally, or [[slave]]{{IdeologyIcon}}, you need to [[draft]] a colonist and select the target to capture. The colonist will then walk up to the target and attempt a capture. The chance of success depends on their [[Arrest Success Chance]], and will be displayed on the prompt. Arrest success chance largely depends on [[Social]] skill, but is negatively affected by [[Manipulation]] penalties. If the arrest fails, the target will go [[berserk]]. Pawns with the [[dead calm]] gene{{BiotechIcon}} always have a 100% success chance, regardless of arrester stats, and thus will never go berserk when arrested.
** Colonists can be captured even during a [[mental break]], except for [[berserk]]. This immediately ends most mental breaks, without catharsis. When released, colonists will get the {{--|6}} ''Was imprisoned'' [[mood]]let for 12 days. This mood penalty will not occur if the colonist is instead re-recruited. Arrests will not end the [[Mental break#Run wild|run wild]] or [[mental break#Catatonic breakdown|catatonic breakdown]] mental breaks.

If you attempt to capture a pawn from a neutral or allied [[faction]], the faction will immediately turn hostile. This includes [[transport pod]] crashes, if they happen to be part of an existing faction.

If you need to capture a pawn, then [[sleeping spot]]s can be used to instantly create a prison and bed space anywhere indoors. You can also turn a colonist bedroom into a prison.

=== Reasons to imprison ===
* To recruit raiders, guests, or transport pod crashes into a colony.
* To use raiders for their [[human resources]].
* To end most [[mental break]]s. Colonists can immediately be released afterwards.
* To keep a colonist restrained in order to overcome [[drug]] withdrawal.
* To convert a colonist or [[slave]] to a desired [[ideoligion]].{{IdeologyIcon}}
* To act as sources of [[Bloodfeeder|bloodfeeding]] or [[hemogen pack]]s.{{BiotechIcon}}
* To sell the prisoner.
* For raiders, to release them for a goodwill gain of the enemy faction (faction must not be permanently hostile and the released prisoner must exit the map healthy).

== Prisons ==
[[File:Thank you Megasloth for letting my prisoners run.png|thumb|right|350px|Megasloth getting sheared at the exit of a prison door, holding it open for a prisoner to escape.]]
Prisons are required to hold prisoners.
=== Creation ===
A prison must be designated in a fully enclosed [[room]], closed off with [[wall]]s and other impassable objects like [[door]]s, [[cooler]]s and [[nutrient paste dispenser]]s. Prisoners cannot be captured unless the prison is enclosed, and mobile prisoners will walk out of the map if an opening exists.

In order to actually form a prison, at least 1 [[bed]] or [[sleeping spot]] must be placed. Selecting the bed allows you to set "For Prisoners". Colonists and [[slaves]]{{IdeologyIcon}} may not share the same room as a prisoner; when 1 bed is set to prisoners, all beds will be converted to prison beds. The beds will turn orange to signify this, and the whole room gains an orange outline when selected. In order to actually capture a prisoner, there must be an open sleeping area for them to stay.

=== General ===
A prison is called a ''prison cell'' if there is 1 bed available, or a ''prison barracks'' if there are multiple beds. A prison is otherwise treated as a bed room or barracks, including [[mood]] impacts for its Impressiveness.

Prisoners can only use items that are in their cell. Food, beds, and [[nutrient paste dispenser]]s placed inside a prison are reserved for prisoner use. While a colonist can be ordered to eat food placed in a prison cell, they will not automatically do so. Colonists on the food binge [[mental break]], as well as [[animal]]s, will ignore a prison for this purpose.

Unless you want your prisoners to die, make sure that it is hospitable. Regulate the [[temperature]], or give prisoners sufficiently insulating [[clothing]], such as [[tribalwear]]. Make sure that food gets to a prisoner (either via a storage zone, warden delivery, or [[nutrient paste dispenser]]). Otherwise, see [[#Mood regulation]] for how to make your prison better for the inmates... or worse.

== Interaction ==
Players can assign wardens to do the following tasks:
* '''[[#Resistance|Recruit]]''' - Reduces the prisoner's [[#Resistance|resistance]], then attempts to recruit.
* '''[[#Resistance|Reduce resistance]]''' - Reduces the prisoner's [[#Resistance|resistance]], does not recruit.
* '''[[#Release|Release]]''' - Releases the prisoner. Imprisoned colonists will rejoin the colony, while other factions will attempt to leave the map.
* '''[[#Execute|Execute]]''' - Order wardens to kill the prisoner.

The following options are added by [[DLC]]:
* '''[[#Will|Enslave]]'''{{IdeologyIcon}} - Reduces the prisoner's [[#Will|will]], then forces them into [[slave]]ry.
* '''[[#Will|Reduce will]]'''{{IdeologyIcon}} - Reduces the prisoner's [[#Will|will]], does not enslave them.
* '''[[#Convert|Convert]]'''{{IdeologyIcon}} - Attempts to convert the prisoner into a warden's [[ideoligion]].
* '''[[#Bloodfeed|Bloodfeed]]'''{{BiotechIcon}} - [[Sanguophage]]s and other pawns with the [[Bloodfeeder]] [[gene]] will drink the prisoner's blood.
* '''[[#Hemogen farm|Hemogen Farm]]'''{{BiotechIcon}} - Pawns assigned to the [[Work#Doctor|Doctor]] worktype will automatically extract [[hemogen pack]]s from the prisoner.

=== Resistance ===
{{see also|#Recruitment{{!}}Recruitment}}
Prisoners start with '''resistance''', or unwillingness to join the colony. This must be lowered to 0 for recruitment attempts to begin. Unwaveringly loyal prisoners do not have a resistance stat, and can't be recruited.

Under the ''Recruit'' or ''Reduce Resistance'' orders, wardens will attempt to lower the resistance. How much is reduced depends on a prisoner's [[mood]], the warden's [[Negotiation Ability]], and the prisoner's [[opinion]] of the warden. Wardens with more [[Social]] skill have a greater Negotiation Ability. There is a delay between each conversation.

Once resistance hits 0, wardens will try to convince the prisoner to join the colony, with a chance to succeed, depending on each prisoner's recruitment difficulty percentage, their current mood, faction, how many colonists you currently have, as well as your [[storyteller]]. If the prisoner is assigned to ''Reduce Resistance'', then wardens will continue to converse without actually recruiting.

For exact mechanics and chances of recruitment, see [[#Recruitment]].

==== Will ====
Enslave{{IdeologyIcon}} and Reduce Will{{IdeologyIcon}} work analogously to Recruit and Reduce Resistance, except that the end result is that the prisoner becomes a [[slave]]{{IdeologyIcon}}. A prisoner starts with much less will than they do resistance.

==== Tame ====
A [[wild man]] can be arrested and imprisoned. However, they must be [[tame]]d using the usual [[animal]] mechanics, rather than being recruited as a prisoner. Once tamed, they will join the colony as a colonist.

=== Release ===
Wardens will take the prisoner outside your colony, and free the prisoner. "Outside the colony" means beyond your outermost line of connected walls, so it could be just out the door, or across most of the map if your defenses stretch that far.

Releasing a prisoner of another faction will give a [[goodwill]] boost of +12. In order to count towards goodwill, the prisoner must successfully leave the map healthy, with any wounds tended to. Prisoners that can't walk can't be released. Pirates and savage tribes do not interact with goodwill, so releasing them has no effect.

Releasing a colonist will have them rejoin your colony. [[Slave]]s retain their home faction.

=== Execute ===
Wardens will cut a prisoner's neck immediately, killing them without fail. This is a different action from the ''Prisoner execution'' [[ritual]].

Executing guilty prisoners - those who have harmed the colony in 24 hours - give a {{--|2}} [[mood]]let to non-[[Psychopath]] colonists. Executing a non-guilty prisoner increases the penalty to {{--|5}}.

Colonists following an [[ideoligion]]{{IdeologyIcon}} with the [[Ideoligion#Execution|Execution: Respected if Guilty]] precept instead gain a {{+|3}} [[mood]]let for executing a guilty prisoner, with the executioner gaining {{+|10}} mood instead. The [[Ideoligion#Execution|Execution: Required]] precept gains the same moodlets (but shorter) for executing anyone. If the execution was desired by precept, then fluid ideoligions gain a development point.

Executed prisoners who are then [[Resurrector mech serum|resurrected]] will have the execute toggle deselected to prevent their immediate re-execution.

=== Convert ===
{{Ideology|section=1}}
Attempts to [[Ideoligion#Conversion|convert]] the prisoner to the warden's own [[ideoligion]]. The target ideoligion can be selected, which will only allow wardens of that ideoligion to convert.

This is functionally the same as [[Ideoligion#Conversion|regular conversion]] that can occur randomly between colonists, except that it is done on a regular basis.

=== Hemogen ===
{{Biotech|section=1}}
==== Bloodfeed ====
Pawns with the ''Bloodfeeder'' [[gene]] will automatically drink the blood from a prisoner, directly. This happens when a bloodfeeder is below their desired Hemogen and if the bloodfeeding would not kill the prisoner.

==== Hemogen farm ====
Automatically orders the operation extract [[hemogen pack]] when a prisoner's [[blood loss]] level reaches 0. In addition to creating drinkable hemogen, it also trains the surgeon's Medical skill.

=== Other ===
* Prisoners can be escorted by a warden to a prisoner bed. Prisoners can be escorted to a prisoner medical bed, if needed, without a risk of escape.
* Prisoners can initiate social fights with other prisoners.
* Prisoners can be given any number of medical [[operation]]s. This includes injecting [[drug]]s, installing [[artificial body parts]], [[organ harvesting]], and more.
* Prisoners are valid targets for a [[gene extractor]]{{BiotechIcon}}, [[subcore softscanner]]{{BiotechIcon}}, or [[subcore ripscanner]]{{BiotechIcon}}.
* Prisoners can be sold to a [[faction base]] or slaver for [[silver]], or a royal tribute collector{{RoyaltyIcon}} for [[honor]]. Colonists who do not like slavery will get a -3 moodlet, modified by [[ideoligion]]{{IdeologyIcon}}.
* If a prisoner dies, the mood penalty depends on their cause of death. "Intentional" means, like violent combat, count as an execution.

== Prison break ==
{{Template:Prison Break}}
{{Clear}}

== Recruitment ==
In order to start recruitment, a target pawn must first be captured, and become a prisoner. Prisoners then must be set to "Recruit" (or "Reduce Resistance" and then "Recruit") in the "Prisoner" tab of their personal info box (bottom left of screen when pawn is selected).

Then colonists assigned to wardening will "chat" with the target prisoner. This can be repeated every several hours, each one reducing [[#Resistance|Resistance]] by a predictable amount (based on the Social pawn's Social skill and the target's Mood).

=== Starting resistance ===
Each prisoner has their own recruitment difficulty:
* The maximum difficulty is 99%, while the minimum is 10%. The average is 50% with a standard deviation of 15%.
* For each level of technology between your faction and the enemy's, the difficulty is increased by 16%. [[New Tribe]]s have a harder time recruiting outlanders, for instance.
* The [[storyteller]] will change the recruitment difficulty of prisoners depending on your existing population.

A prisoner's base resistance depends on their difficulty. At 10% difficulty, prisoners have no starting resistance. At 50%, they have 15. At 90%, they have 25. At 100%, they have 50.

This is multiplied by the storyteller's 'population intent' factor- the greater your population, the less the storyteller will want you to have an increase in population, and hence the higher the starting resistance. At -1 intent, the resistance is multiplied by 2. At 0, the resistance is multiplied by 1.5. At 1, the resistance is multiplied by 1. At 2, the resistance is multiplied by 0.8.

Finally, the resistance is multiplied by a random factor between 0.8 and 1.2.

=== Resistance reduction ===
A warden will reduce a base of 1.0 resistance per conversation. This is multiplied by:

'''Prisoner's [[opinion]] of the warden:'''
* At -100 opinion, the resistance reduction factor is 50%.
* At 0 opinion, the resistance reduction factor is 100%.
* At 100 opinion, the resistance reduction factor is 150%.

'''Prisoner [[mood]]:'''
* At 0% current mood, the resistance reduction factor is 20%.
* At 50% mood, the resistance reduction factor is 100%.
* At 100% mood, the resistance reduction factor is 150%.

'''Negotiation Ability:'''
* See [[Negotiation Ability]].

==== Word of Trust ====
The [[Word of trust]] psycast {{RoyaltyIcon}} will reduce resistance by 20, multiplied directly by the prisoner's [[Psychic Sensitivity]] and no other factors.

== Tips ==
=== Mood regulation ===
{{Stub|section=1|reason=Only some mental breaks are available to prisoners. Which? Expand on how that affects strategy and options}}
Increasing [[mood]] makes prisoners easier to recruit, and less likely to go [[berserk]]. If you want to increase prisoner mood, you can do the following:
* Give prisoners separate rooms, preferably one that isn't cramped.
* Give a prisoners a source of [[light]], a [[table]] and [[chair]], and a decent [[bed]].
* Increase the impressiveness of a room with [[sculpture]]s, [[stone tile]]s, etc.
* Give the prisoner [[fine meal]]s, [[lavish meal]]s, or even [[drug]]s.

=== Changing ideoligion ===
{{Ideology|section=1}}
If you want to change the target's [[ideoligion]], then instead try and make the prisoner upset. Lower mood reduces [[certainty]] gain, and may cause a [[Mental break#Crisis of belief|Crisis of Belief]] extreme mental break, which reduces certainty by 50%. The following can help with decreasing mood:
* Keep prisoners in a confined, dark space, without a bed or furniture. Even if there's only 1 prisoner, placing 2 [[sleeping spot]]s will create a prison barracks.
* Feed the pawn [[human meat]], [[insect meat]], [[raw food]], or [[kibble]]. Certain ideoligions can make some of these foods more desirable, but kibble is never desirable to eat.
* Keep them in [[pain]]. Inflicting [[injury]] comes at the risk of scarring or permanent damage, however, and a [[mindscrew]] {{RoyaltyIcon}} cannot be removed by traditional methods once the pawn is converted. A [[torture crown]] is a risk free way of inflicting pain, but dressing prisoners has its own difficulties.
Keep in mind that crises of belief that would drop a pawn's certainty to or below 0%, will instead convert the pawn to a weighted randomly selected ideoligion with a new certainty. While this process might select the intended ideoligion, it may not while also requiring their certainty be reduced again. If a pawn's certainty is below 50%, consider improving their mood above their extreme [[mental break threshold]] to prevent this.

It is also worth considering the individual pawn when deciding on an approach. The first concern are the [[traits]] - many traits affect the [[Global Certainty Loss Factor]] of a pawn, which in turn affect the efficacy of conversion attempts by wardens. For pawns with a high factor, traditional conversion will be effective, while forcing a crisis of belief may be all but necessary. For further details, including a list of traits that affect the factor, see [[Certainty]] and [[Global Certainty Loss Factor]].

The second concern are [[xenotypes]]{{BiotechIcon}} with the [[Aggressive]] and [[Hyper-aggressive]] genes.{{BiotechIcon}} Those with aggressive, including all [[yttakin]],{{BiotechIcon}} [[wasters]],{{BiotechIcon}} [[neanderthals]],{{BiotechIcon}} and [[sanguophages]],{{BiotechIcon}} are much more likely to have a berserk mental break, proportionally reducing the chances of a crisis of belief. Meanwhile those with hyper-aggressive will essentially never select the crisis, making pawns such as [[hussars]]{{BiotechIcon}} all but impossible to convert by crisis.

=== Prisoner suppression ===
Whenever they are [[berserk]], under a [[#Prison break|prison break]], or just escaping, sometimes you will need to subdue a prisoner. When berserk, prisoners will fight other prisoners, then will punch the weakest area (usually a [[door]]) to escape. When under a prisoner break, they can just open the door.

If you need to keep the prisoner alive, it is best to use low damage weapons and attacks - even just melee attacks with a gun or bare fists. Several unskilled pawns work better than 1 skilled one. For berserkers, you can have a skilled [[Construction]] pawn constantly repair the door. This trains Construction but is labor intensive. You can also wall the prisoner in, which will cause them to stop attacking the door and just wander around in their cell instead.

If free roaming [[animal]]s are within the prison, then [[berserk]]ing prisoners will prioritize them over breaking out. You can place [[animal sleeping spot]]s inside the prison for an automatic form of prisoner suppression. Note that animals are slightly more dangerous than humans. In addition, most animals will create a large amount of [[filth]], quickly lowering the room's quality. You may want to use [[straw matting]].

=== Unwanted prisoners ===
Enemies who have fallen in battle may not always be worth capturing in the first place. For example, a hostile with a shattered spine will require a [[bionic spine]] to replace, which may not be worth it. Unwavering prisoners can't be recruited normally, so fall under the same boat.

There are several ways to dispose of these prisoners:
* '''Release:''' The least upsetting way to remove a prisoner. Colonists will not become upset if an enemy prisoner is released, and it may increase [[goodwill]] by a small amount.
* '''Expendables:''' This is not exactly "getting rid of them", as much as making best (and ultimately temporary) use of them. Recruit them, and send them out for a long [[caravan]] that you wouldn't expend another colonist for. You can set them on a trading expedition, or scout a base/map. Or, you can use them as a meatshield. A "colonist" dying still gives a negative moodlet (-3, same as incidental death or non-guilty euthanasia), which is affected by [[opinion]]. Cut off their tongue to prevent social interaction from happening. Of course, unwavering prisoners can't be recruited.
* '''Euthanasia:''' Execute in a more humane fashion by neck cut. This costs 1x [[herbal medicine]] (or better) and trains Medical experience. An 'innocent' prisoner going through euthanasia is less upsetting than an innocent execution.
* '''Execution:''' Execute a prisoner in a raw manner. Those with an [[ideoligion]] favoring execution will enjoy it. With a fluid ideoligion, execution is a very easy way to gain development points (so long as it is Respected if Guilty).
* '''[[Human resources]]:''' Use prisoners for their parts. Artificial limbs can be removed without penalty.
** [[Organ harvesting]]: A [[kidney]] and [[lung]] can be harvested without death, and a [[heart]], [[liver]], or second kidney/lung can be taken to kill. Unless Organ Use is acceptable by [[ideoligion]], this comes with a -6 [[mood]] penalty (stacks, but diminishing) for the colony, and even more if the prisoner was killed.
** Used for a [[gene extractor]]{{BiotechIcon}} or [[subcore ripscanner]]{{BiotechIcon}}, the latter of which is fatal.
* '''Selling:''' Prisoners can be sold for money at a [[faction base]] or slaver, or exchanged for [[honor]]{{RoyaltyIcon}} from a royal tribute collector. Each sold prisoner gives -3 [[mood]].

== Version history ==
* [[Version/0.8.657|0.8.657]] - You can now release prisoners. This gains you goodwill from their faction.
* [[Version/0.13.1135|0.13.1135]] - Prison breaks added.
* 1.1 - Interface now reports the chance of a successful arrest before you try to make it.
* [[Version/1.1.2570|1.1.2570]] - Escaping prisoners are no longer able to equip [[Persona weapons|bladelinked]] or [[biocoded]] weapons.
* [[Version/1.3.3066|1.3.3066]] - Prisoner escape chance is multiplied by the number of exits the prisoner has. Escaping prisoners will attack enemies with weapons they pick up, including [[orbital bombardment targeter]]s, [[orbital power beam targeter]]s, and [[tornado generator]]s.
* [[Version/1.4.3523|1.4.3523]] - Unwavering prisoners added. Fix: Resurrected executed prisoners retain the execute option and usually immediately get executed after being resurrected.
* [[Version/1.4.3529|1.4.3529]] - Fix: Hemogen extraction can get "stuck" on. Fix exploit: Unwaveringly loyal can be bypassed by enslaving prisoners. Fix exploit: Capture>Enslave>Imprison>Release recruits pawns immediately.
* [[Version/1.4.3555|1.4.3555]] - Fix: Enslaving a pawn removes unwaveringly loyal. Fix: Unwaveringly loyal inspect pane text not appearing for slaves.
* [[Version/1.4.3613|1.4.3613]] - Fix: Child prisoners attempt to wear adult clothing, causing it to disappear.
* [[Version/1.4.3641|1.4.3641]] - Fix: Error on releasing space refugee prisoners.
* [[Version/1.4.3682|1.4.3682]] - Fix: [[Dead calm]] pawns go berserk when arresting fails. Fix: Captured prisoners escaping from reformed caravans.
* [[Version/1.5.4062|1.5.4062]] - Fix: The "run wild" mental break can occur on unwaveringly loyal pawns, causing them to be tameable. Unlisted change: Unwaveringly loyal prisoners can be converted to different ideologies. Fix: Prisoners can start social fights with non-prisoners.
* [[Version/1.5.4062|1.5.4062]] - Fix: Rounding shows resistance at 0.0, but recruitment isn't available yet.
[[Category:Characters]]

Blood rain (ritual)

2026-03-10T00:57:13Z

Aelanna: Merge edit by 47.204.19.195

{{Anomaly}}
{{Stub|reason= General - Missing real summary and analysis. Also needs participant kinds and numbers}}
{{About|the [[psychic ritual]]|weather event it causes|Blood rain}}
{{Infobox main|psycast
| name = Blood rain
| image = Psychic ritual - Blood rain.png
| type = Psychic ritual
| description = Cast a ritual which causes blood-like psychofluid to fall from the sky. The fluid will slowly drive exposed humans and animals into a berserk frenzy. Traits and psychic sensitivity modulate the effect.
| research = Blood rain
| ritual duration = 5000
| ritual cooldown = 1500000
| resource 1 = Bioferrite
| resource 1 amount = 70
}}
'''Blood rain''' is a [[psychic ritual]] that causes the [[blood rain]] weather event to start, which inflicts slowly increasing [[melee damage factor]] buffs and [[mood]] penalties on those exposed to it, before finally driving them berserk.

== Acquisition ==
{{Acquisition}}

== Summary ==
Effect duration ranges from 3 hours at 0% ritual quality to 16 hours at 100% quality.

Colony [[animals]] will retreat indoors and inside their barn to avoid being exposed to blood rain.

== Analysis ==

As of 1.6 Blood Rain is bugged due to incorrectly calculating ticks, rendering it impossible to cause any pawn to reach an enraged state. It would require a minimum of six blood rain's worth of exposure at the current rate for a chance to have an effect. A temporary fix is available [https://steamcommunity.com/sharedfiles/filedetails/?id=3665183535 here.] This issue has already been patched on Unstable, and once it is pushed to the live version of the game, this note should be taken down.

Blood rain is a dedicated anti-siege ritual. While it is the single most expensive ritual in terms of bioferrite, and it requires prolonged exposure to the elements that almost no enemy raid types will wait around for, the Siege raid type is the best case scenario for it, involving many enemies standing out for long periods in the weather. Eventually, exposed pawns will reach 100% exposure, causing them to attack all targets around them. This includes animals, causing them to turn Manhunter. Humanoid pawns will lose their bezerk status as soon as the Blood Rage effect wears off, while Manhunter animals will remain as Manhunters until the next time they fall asleep, identically to animals that turn Manhunter from being attacked.

This purpose extends to mechanoid sieges, as well. While mechanoids are entirely unaffected by the blood rain, the ritual turning a portion, possibly even a majority, of the wild animals on your tile into Manhunters will cause them to attack any non-sleeping mechanoids present. Unlike intentionally botching a [[Draw animals]] ritual, Blood Rain is likely to turn half to three quarters of your wildlife population into Manhunters temporarily, while an intentionally failed Draw Animals draws a number of Manhunters based on a colony's total wealth and associated threat points scaling, and which will not calm down overnight, requiring five days until they die off.

It is unwise to perform a Blood Rain against non-siege raids. Not only are they likely to be far too short for the blood rage to build to a beneficial effect, the short term effect of exposure is an increased melee damage factor. The lack of benefits in the short term for ensuring enemy raiders deal more melee damage against your colony is self explanatory. If your colony ranches animals, then it would also be prudent to ensure any pens have a roof over them, before you send your own chicken farm or horse stable into a manhunting rage.

== Version history ==
* [[Anomaly DLC]] Release - Added.

{{Nav|psychic rituals|wide}}

[[Category: Psychic rituals]]

Slavery

2026-02-22T01:35:54Z

Aelanna: Cleaned up the recently edited sentence.

{{Ideology}}
{{Rewrite|reason=Previous major rewrite lost information re: raid points. Verify any other losses}}
{{For|selling prisoners, which is also considered "slavery" |Prisoners}}
'''Slavery''' in base game RimWorld is limited to selling [[prisoner]]s for profit, at the cost of a [[mood]] hit for anyone not a [[psychopath]]. Purchasing a slave, meanwhile, will immediately free them from slavery and join them into the colony, with a mood buff. The [[Ideology DLC]] significantly expands on the concept, allowing prisoners to be enslaved and forced to work and perform tasks.

== Acquiring slaves ==
Slaves can be created by reducing the will of a [[prisoner]] to zero, or by attempting to enslave a prisoner while benefiting from a recruitment [[Mental inspiration#Inspired recruitment|inspiration]]. A prisoner's starting will is usually much lower than their resistance (which would recruit them as a colonist).

== Summary ==
Slaves are controllable pawns, much like a colonist. They have many functional differences but act just the same. Slaves are prone to [[#Slave rebellion|slave rebellions]].

Slaves contribute 75% of the [[raid points]] of an equivalent colonist.

=== Work ===
A slave will have 85% [[Global Work Speed]] - they have no motivation to work as hard. To compensate, they have no need for [[Recreation]], and will have increased mood through expectations.

Slaves are unable to do the Warden, Hunt, Art, or Research tasks. They are additionally unable to:
* Tasks that require a minimum [[Intellectual]] skill greater than 0 such as crafting [[Medicine]] as slaves are considered to have 0 skill regardless of their actual skill level prior to enslavement. Despite [[Drug Synthesis Speed]] scaling with Intellectual they are still capable of doing tasks that use this stat for scaling, albeit slowly.
* Request caravans, military aid, or persona core location via [[comms console]]
* Call royal [[permit]]s{{RoyaltyIcon}}
* Be an ideoligious [[role]]
However, slavery overrides ''all'' other work exceptions. For example, if a colonist would be unable to do Dumb Labor, enslaving will force them to allow Dumb Labor.

Unlike [[prisoner]]s, male slaves can fertilize [[embryo]]s.{{BiotechIcon}}

=== Expectations ===
{{See also|Expectations}}
Slaves do not have the default [[expectations]] of colonists. Instead they have unique expectations with a generally higher mood boost. Slave expectations replace colonist expectations based on what the pawn's expectations would be if they were a colonist based on colony wealth and noble status.

{| class="wikitable"
|- 
! Expectation !! Mood Effect !! Replaces Colonist Expectation
|-
| Destitute slave expectations || {{+|46}} || Extremely low expectations
|-
| Poor slave expectations || {{+|40}} || Very low expectations
|-
| Meager slave expectations || {{+|34}} || Low expectations
|-
| Slave expectations || {{+|28}} || All other Expectations
|}

=== Relationships ===
* Slaves never insult or social fight with non-slave pawns. They are half as likely to social fight with each other.
* Slaves cannot share a [[double bed]] with non slaves colonists, even if they are married.
* Slaves can share [[bed]]rooms with colonists, however the colonists will receive {{--|3}} mood for doing so (unless they are in a relationship).

Other colonists will see slavery as either an abhorrent or honorable act, depending on the Slavery [[precept]].

== Slave rebellion ==
{{Stub|section=1|reason =Reports that pawns do not revolt on underground maps}}
Slaves will occasionally rebel, staging something similar to a prison break. Slaves will turn hostile and uncontrollable, and will try to find weapons to attack nearby colonists. The rebellion interval is based on mood, suppression, proximity of weapons, escape route, and the presence of colonists on the map, with a base interval of 45 days. The time displayed is based on time awake - that is, if a slave sleeps 8 hours of every 24, the actual mean time between rebellions will be 50% longer. A displayed {{MTB}} of 2 years will actually be a {{MTB}} of 3 years.

Slave rebellions come in several different types: Grand, Local, and Single. A grand escape involves every valid slave on the map rebelling, while a local escape chooses a given slave as a locus with any valid slaves within 35 tiles also rebelling. A single rebellion is, as the name implies, a rebellion by a single slave.

Only non-downed, non-mental breaking, awake, slaves can join a rebellion. Thus, by assigning slaves different shifts, the maximum number of slaves rebelling can be limited.

Weapons such as [[Wood]], [[EMP grenades]]/[[EMP launcher|launchers]], and [[Smoke launcher]]s will not increase rebellion chance, despite being weapons. Rebellious slaves will take ranged weapons even if equipped with [[shield belt]]s, dropping the belts in the process.

While in [[orbit]]{{OdysseyIcon}} slaves cannot rebel at all as they cannot leave the map under normal circumstances while in space.

{| class="wikitable"
| '''Mean Time Between Rebellions''' = 45/(Moving Factor * Suppression Factor * Slave Count Factor * Mood Factor * Room Edge Factor * Weapon Factor * Unattended Factor)
|}
Where:
* Moving Factor = A curve dependent on the current [[Moving]] capacity of the slave, defined by 3 points and linearly interpolated between them. 0.01x at 0% (though note that a pawn that cannot move is not valid for a rebellion anyway), 0.5x at 50% and 1x at 100%. This very closely approximates a straight scalar based on the Moving capacity, but is slightly different. Also note that this is Moving capacity, not [[move speed]], so slowing a pawn down with [[peg leg]]s will make rebellions less frequent, but slowing them down with a [[flak vest]] will not.
* Suppression Factor = A curve dependent on the current suppression value of the slave, defined by 4 points and linearly interpolated between them. 5x at 0%, 1.5x at 33.3%, 1x at 50%, 0.25x at 100%.
* Slave Count Factor = A curve dependent on the number of slaves loaded on a map, defined by 5 points and linearly interpolated between them. 1x at 1 slave, 0.75x at 2 slaves, 0.5x at 5 slaves, 0.3x at 10 slaves. 0.2x at 20 slaves. Note that despite making each slave individually less likely to rebel, having more slaves rolling for rebellions actually increases the chance. Also note that these slaves don't need to be valid slaves for a rebellion, they must simply be alive and on the map.
* Mood Factor = A curve dependent on the [[mood]] of the slave, defined by three points and linearly interpolated between them. 1.5x at 0% mood, 1x at 50% mood, 0.8x at 100% mood.
* Room Edge Factor = 1.7 when in a room that touches the map edge including being completely outdoors. 1 otherwise.
* Weapon Factor = 4 when within 7 tile range of a usable weapon, or if indoors (in a room not considered outdoors) in the same room as a usable weapon. 1 otherwise. [[Body part weapons]] do not count for the purposes of this check.
* Unattended Factor = 20 when on a map without a colonist that is not downed, dead or a slave. 1 otherwise.

== Wardening ==
Like [[prisoner]]s, slaves can be interacted with by colonists with the Warden task.

* '''Suppress''' - Intimidate the slave, causing their suppression to rise up, which lowers the chance of rebellion.
* '''Imprison''' - Arrest the slave, turning them back into a [[prisoner]]. You will need to reduce their will again to enslave them again.
* '''Emancipate''' - Free the slave. If the slave belonged to another faction, you will gain [[goodwill]] with that faction.
* '''Execute''' - Kill the slave.

== Suppression ==
{{Stub|section=1|reason=Children have different fall rates? }}
Suppression is one of the stats used to calculate the slave rebellion interval. The higher the suppression, the longer the expected interval in between rebellions. The suppression of a slave can be increased by interacting with them, melee attacking them with a colonist or executing other slaves or prisoners. Over time, the suppression level lowers depending on its current level by up to 20% per day. It will continue to tick down when the pawn is asleep.

{| class="wikitable"
|-
! Suppression !! Suppression loss<br/>(per day)
|-
| 30% - 100% || {{--|20%}}
|-
| >15% - <30% || {{--|10%}}
|-
| 0% - 15% || {{--|5%}}
|}

The amount of suppression lost can be increased or decreased if the slave is wearing the following things:
{| class="wikitable sortable"
|-
! Item !! Suppression loss offset<br/>(per day)
|-
| [[Slave collar]] || {{+|15%}}
|-
| [[Slave body strap]] || {{+|15%}}
|-
| [[Cowboy hat]] || {{--|5%}}
|-
| [[Bowler hat]] || {{--|5%}}
|-
| [[Tribal headdress]] || {{--|10%}}
|-
| [[Veil]] || {{--|10%}}
|-
| [[Marine helmet]] || {{--|10%}}
|-
| [[Duster]] || {{--|5%}}
|-
| [[Marine armor]] || {{--|30%}}
|-
| [[Prestige marine helmet]] {{RoyaltyIcon}} || {{--|10%}}
|-
| [[Prestige marine armor]] {{RoyaltyIcon}} || {{--|30%}}
|-
| [[Grenadier armor]] {{RoyaltyIcon}} || {{--|30%}}
|-
| [[Eltex shirt]] {{RoyaltyIcon}} || {{--|20%}}
|-
| [[Eltex vest]] {{RoyaltyIcon}} || {{--|20%}}
|-
| [[Eltex robe]] {{RoyaltyIcon}} || {{--|20%}}
|-
| [[Formal shirt]] {{RoyaltyIcon}} || {{--|10%}}
|-
| [[Corset]] {{RoyaltyIcon}} || {{--|10%}}
|-
| [[Formal vest]] {{RoyaltyIcon}} || {{--|10%}}
|-
| [[Prestige robe]] {{RoyaltyIcon}} || {{--|20%}}
|-
| [[Ladies hat]] {{RoyaltyIcon}} || {{--|5%}}
|-
| [[Top hat]] {{RoyaltyIcon}} || {{--|5%}}
|-
| [[Coronet]] {{RoyaltyIcon}} || {{--|20%}}
|-
| [[Crown]] {{RoyaltyIcon}} || {{--|30%}}
|-
| [[Stellic crown]] {{RoyaltyIcon}} || {{--|30%}}
|-
| [[Beret]] {{RoyaltyIcon}} || {{--|5%}}
|-
| [[Mechlord suit]]{{BiotechIcon}} || {{--|30%}}
|}

A suppression loss of less than 0% per day will not increase the suppression. Since the default loss is at a maximum of 20% per day, a slave collar combined with body straps is enough to keep up the suppression of a slave unless they are wearing apparel that increases suppression loss above 10%. Since a negative loss has no effect, increasing Terror while slaves wear slave collars and body straps is useless unless you also wish to outfit the slave with suppression-decreasing apparel, such as dusters in hot [[biomes]] or marine armor for combat slaves.

=== Warden suppression ===
Each time a warden suppresses a slave, it increments their suppression by a value dependent on the [[Suppression Power]] of the warden and the current suppression of the slave.
Namely:

{| class="wikitable"
|-
| '''Suppression Change = Suppression Power * Suppression Curve Factor'''
|}

{| class="wikitable"
|-
! CurrentSuppressionFactorCurve
|-
| {{Graph:Chart|width=200|height=200|xAxisTitle=Current Suppression (%))|yAxisTitle=Suppression Multiplier|type=line|x=0, 50, 100 |y1= 2, 1, 0.5}}
|}

For example, a colonist with [[Skills#Social|Social]] skill of 10 has a Suppression Power of 28%. A slave with a current Suppression value of 0 has a suppression curve factor of 2x. Thus, that colonist suppressing that slave would result in the slave's suppression increasing by 56%. This also means that a skill 20 pawn will always fully supress a slave.

Each suppression attempt takes {{ticks|180}} of work.

[[Authority cap]]s improve the suppression power of the wearer. See that page for details.

=== Melee suppression ===
{{Stub|section=1|reason=Exact equation depends on CurrentSuppressionFactorCurve - needs to be worked out and added}}
Any colonist can suppress a pawn by performing melee attacks against them. Each attack increases suppression at a rate dependent on the current suppression and the damage dealt, with more damage suppressing more

=== Terror ===
{{Stub|section=1|reason= A number of check tags, and even with them, theres mechanical detail missing. Terror mechanics are poorly documented and [[terror]], [[terror sculpture]], [[gibbet cage]], and [[skullspike]] all need detail.}}
{{Quote|''Terror is a way to keep slaves suppressed. It rises when the slave spends time near terrifying things like terror sculptures. A slave can only be affected by three terror sources at a time. While terror is high, suppression falls slower.''|Terror description}}

Terror is stat of slaves that ranges from 0% to 100% and is raised by being in proximity to terror creating furniture. While slaves are affected by terror, the rate at which they lose suppression is reduced, depending on their current terror.

The relationship between terror and reduction in suppression loss is as follows:
{| class="wikitable"
|-
! colspan=2 | Suppression Loss Rate Offset by Terror Percentage
|-
| {{Graph:Chart|width=200|height=200|xAxisTitle=Terror (%)|yAxisTitle=Suppression Loss Rate Offset (%) |type=line|x=0, 25, 50, 100|y1=0, 15, 25, 45}}
| The offset to suppression loss rate is linearly interpolated between the following points:
* {{+|15%}} at 25% terror
* {{+|25%}} at 50% terror
* {{+|45%}} at 100% terror
|}
For example, a pawn with a current suppression level of 80% would lose, by default, {{--|20%}} suppression per day. If they had 30% terror, this would result in an offset of {{+|18%}} to their suppression loss rate, resulting in a final loss rate of {{--|2%}}

Note that pawns that are asleep do not experience terror but still have their suppression tick down. Also note the terror does not have "memory" or any gradual decline after leaving the radius of the sources - after a short period{{Check Tag|How long?|Reports of ~15 seconds?}} when the next check for terror sources is performed, the terror will instantly drop.

Terror sources stack additively, up to three times structures.{{Check Tag|Which three?|Is it the best three or the most recently seen three?}} Sources of terror are as follows:
{| {{STDT|sortable text-center}}
|-
! colspan="2" | Source !! Strength !! Radius
|-
! {{Icon Small|Skullspike|24}}
! [[Skullspike]]
| {{+|25%}}
| ? Tiles{{Check Tag|Detail needed}}
|-
! {{Icon Small|Gibbet cage|24}}
! [[Gibbet cage]]
|       '''0%'''/{{+|25%}}<br><small>Empty</small>/<small>Filled</small>
| ? Tiles{{Check Tag|Detail needed}}
|-
! {{Icon Small|Terror sculpture|24}}
! [[Terror sculpture]]
| {{+|3%}}/{{+|6%}}/{{+|10%}}/{{+|15%}}/{{+|20%}}/{{+|30%}}/{{+|40%}}
| ? Tiles{{Check Tag|Detail needed}}
|}

== Analysis ==
Keep slaves in collars and straps. Barring that, build terrorizing furniture in the areas they spend the most time ''awake'' in, such as workshops and kitchens. Terror fixtures are of little use inside a slave's own room.

Keep your weapons inside a room that slaves will rarely, if ever, approach; confining your slaves to a restrictive allowed [[Zone/Area#Allowed area|area]] helps, of course.

Minimize or eliminate the time slaves have access to the map edge. Consider walling off the area that slaves live in, if your entire colony isn't walled off already (doors count as barriers for purposes of map edge access for slaves). If that isn't feasible, keep slaves near the center of your colony as much as possible, and build walls and doors blocking off the ends of alleyways (this also helps slow down raiders that get past your outer defenses or land inside your base outright). Again, confining slaves to an allowed area is critical.

Consider keeping your slaves happy. This is much easier than it might seem, since slaves have a huge baseline mood boost compared to a typical colonist, and will never get upset about lack of recreation. Slaves also get mood bonuses from performing work they're [[Passion|passionate]] about; paradoxically, these bonuses can last longer because the slave need not take recreation breaks. Having them drink [[psychite tea]] every other day will not only boost their mood further but also slightly increase their productivity (though unfortunately the big increase to recreation is wasted). Because slaves return to their rooms by default when in need of medical care, consider making their floors [[steel tile]] for an admittedly expensive increase to both cleanliness and room beauty. Also consider sticking "hand-me-down" beautifying [[sculptures]] in their rooms instead of just selling the old art. On the other hand, [[ascetic]] slaves allow you to have a happy slave with the crummiest room possible. [[Masochist]] slaves will love having a mindscrew implant (though it will lower their sale price), and the pain will lower consciousness, reducing their movement potential and further discouraging rebellion. Or just punch them once in a while. They also like wearing the collar and straps that all slaves should wear anyway. Not only do happy slaves rebel a bit less often, joyful slaves can benefit from [[inspirations]] as other colonists do, making them even more useful as your property.

If you have the [[Royalty]] DLC, consider giving slaves brain implants that cause [[brain shock]] so rebellions can be safely suppressed with no loss of life, even with armed and armored slaves, by using [[EMP]] weapons. Implants such as the [[circadian half-cycler]]{{RoyaltyIcon}} and the [[circadian assistant]]{{RoyaltyIcon}} also increase the total productivity of the slave, and the half-cycler reduces movement capacity by reducing consciousness; the downside is that these implants increase time awake, lowering the {{MTB}} for rebellions.

If you have the [[Anomaly]] DLC, the Bliss Lobotomy procedure can be learned and performed to massively reduce the frequency of an individual slave's rebellion interval at the cost of no longer being able to perform skilled labor and reducing their learning speed. This makes it a very compelling option for slave whose primary role is Hauling, Cleaning, Animal Handling, and/or Doctoring. Lobotomized slaves are so compliant that even when armed their rebellion interval more closely matches that of a normal, unarmed slave. While not entirely without risk, this makes enslaved combatants a viable option especially if they are only armed when there is an active threat. It is important to note that while a lobotomized slave may almost never rebel themselves, other non-lobotomized slaves may start a group rebellion and cause lobotomized slaves to join regardless.

=== Genes ===
{{Biotech|section=1}}
Genetically modifying slaves is overall essential for improving how efficient they are at work and countering their faults.

{| class="wikitable"
|+
Countering Rebellions
|-
! Gene !! Total Metabolic Efficiency !! Commentary
|-
| [[Extra pain]] || {{+|2}} || forces the wimp trait increasing pain shock threshold, this allows rebellions to be dealt with quicker and with less risk of killing the slave, mental breaks should they occur can be dealt with in the same way.
|-
| [[Weak melee damage]]<br>[[Nearsighted]] || {{+|1}}<br>{{+|2}} ||Should be added over [[violence disabled]] this is because pawns incapable of violence will still participate in rebellions and the gene overrides the two actually impactful genes for combat.
|-
| [[Genes#Aptitude|Awful shooting/melee<br>Poor shooting/melee]] || {{+|2}}<br>{{+|1}} || Lowers the skills that they will use for combat during rebellions in addition to being essentially free metabolic efficiency
|-
| [[Very happy]] || {{--|2}} || indirectly makes rebellions less frequent by improving their mood.
|-
| [[Superfast wound healing]]<br>[[Fast wound healing]] || {{--|3}}<br>{{--|2}} || Allows slaves to recover faster after being beaten during rebellions or mental breaks, damaging slaves in melee also raises their suppression far quicker then a warden doing it
|-
| [[Genes#Temperature|Heat/Cold super-tolerant<br>Heat/Cold tolerant]]<br>[[Furskin]]<br>[[Furry tail]] || {{--|2}}<br>{{--|1}}<br>{{--|1}}<br>{{--|1}} || Should be added if in hot or cold biomes this is because Slave body straps occupy the outer layer thus they cannot be equipped with parkas or dusters missing out on additional slave suppression offset.
|}
{| class="wikitable"
|+
Improving and countering their faults
|-
! Gene !! Total Metabolic Efficiency !! Commentary
|-
| [[Genes#Beauty|Very unattractive<br>Unattractive]] || {{+|2}}<br>{{+|1}} || While slaves cannot be ordered to romance other colonists, they will still do it on their own terms, these genes while being free also reduce the chance of undesirable relationships from forming, thus negating the sleeping alone and "My <relationship> died" moodlets slaves cannot share beds with colonists and cannot do loving either.
|-
| [[Genes#Aptitude|Awful intellect/artistic<br>Poor intellect/artistic]] || {{+|2}}<br>{{+|1}} || These skills cannot be used so free metabolic efficiency
|-
| [[Genes#Sleep|No sleep<br>Low sleep]] || {{--|6}}<br>{{--|4}} || can be installed to increase how long slaves are awake for and thus working combined with the lack of recreation need, Makes rebellions larger due to more slaves being awake at the same time.
|-
| [[Smooth tail]]<br>[[Elongated fingers]] || {{--|1}}<br>{{--|1}} || improves manipulation offsetting the lowered work speed.
|-
| [[Genes#Aptitude|Great aptitude<br>Good aptitude]] || {{--|3}}<br>{{--|1}} || Overall depends on what you want the slave to be specialized towards, Crafting can be installed to allow the slave to craft components far sooner, while Mining can allow them to work faster at drills or clearing areas for building, these can turn what is otherwise a garbage pawn into one specialized for certain petty tasks far quicker.
|}
=== Titles ===
{{Royalty|No category}}
{{Main|Titles}}
Slaves can be given honor and ascend the ranks of royalty just as every other pawn can. They function much the same as other nobles, requiring specific clothes, certain standards of bedroom and throne room, etc. with two major exceptions. First is they cannot use permits. Second is that slavery overrides the work type restrictions from conceited nobility.

== Version history ==
* Between 1.2.2723 and [[Version/1.3.3087|1.3.3087]] - Slave sold penalty reduced from -5 to -3.
* [[Version/1.3.3072|1.3.3072]] - Tune slave rebellion chances a bit lower, and reduce the effects of some factors. Slave weapon noticing distance reduced from 10 to 6.9. Couples made of a slave/colonist pair no longer want to sleep together despite not being able to share a bed.
* [[Version/1.3.3074|1.3.3074]] - Slaves no longer slight or insult non-slaves, Slaves never start social fights with non-slaves if insulted, Meleeing a slave now increases suppression, Rebellion chance per slave now relates inversely to the number of slaves on the map, so overall rebellion chance shouldn't climb so aggressively with higher slave counts, Adjust slave rebellion base {{MTB}} 50 days back to 45 days. Ideoligion funerals are no longer expected for slaves. Slaves no longer count for Diversity of Thought. More selective in which weapons increase rebellion chance - now excludes Wood, EMP, Smoke etc.
* [[Version/1.3.3076|1.3.3076]] - Added Alert for likely slave rebellion.
* [[Version/1.3.3087|1.3.3080]] - Rebelling slaves now drop shield belt if they have a ranged weapon
* [[Version/1.3.3087|1.3.3087]] - Lower slave social fight chance by 50%. Killing a slave in a slave rebellion no longer causes 'Witnessed ally's death' thought.
* [[Version/1.3.3117|1.3.3117]] - Fix: Wardens stop suppressing slaves if suppression > 50%. Fix: Selling prisoners doesn't trigger negative thoughts on selling to slavers.
* [[Version/1.3.3200|1.3.3200]] - Slaves are now worth 75% of colonists in terms of map wealth and population.
* [[Version/1.4.3541|1.4.3541]] - Fix: Emancipated slaves that are drafted stay drafted.
* [[Version/1.4.3555|1.4.3555]] - Fix: Enslaving a pawn removes unwaveringly loyal.
* [[Version/1.4.3682|1.4.3682]] - Fix: Slaves freed on exiting map.

[[Category:Game mechanics]]

Modding Tutorials

2026-02-20T21:07:46Z

Aelanna: /* C# Guides */

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)
* [[Modding_Tutorials/Code_FloatMenuOptionProvider|FloatMenuOptionProvider]] - How to use <code>FloatMenuOptionProvider</code> to add right click context menu options to arbitrary targets.
* [[Modding_Tutorials/Code_MendingJob|Example Mending Job]] - How to use a <code>FloatMenuOptionProvider</code> in conjunction with a <code>JobDef</code> and <code>JobDriver</code> in order to create a simple mending function for weapons and apparel.

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
* [[Modding Tutorials/Rituals]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* Ekksu's animal texture guides: [https://imgur.com/a/how-to-make-rimworld-sprites-its-basically-x-with-y-edition-wS3Pt 1] [https://imgur.com/a/how-to-make-rimworld-sprites-theres-nothing-that-looks-like-this-animal-edition-xdDzg 2]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Raider

2026-02-17T16:50:04Z

Aelanna: Clarifying that only HE or incendiary shells can be received as resupply. The game code explicitly only includes shells that directly harm health and explicitly omits antigrain shells. See LordToil_Siege to verify.

{| align=center
| {{Characters_Nav}}
|}
----

<onlyinclude>
{{About|NPC enemies|the ideological meme|Ideoligion#Raider{{!}}Raider}}
{{imagemargin|[[File:raiders_layout_preview.png|124px|right]]|41px}}</div>'''Raiders''' are essentially the main antagonists of ''RimWorld''. They are predatory enemies who appear in events called "Raids" and are sent by the storyteller or by player accepted quests. The group size and strength of a raiding party is determined by 'points', which will be explained in-depth further down this article.</onlyinclude>
{{TOCright}}
Raiders have several [[#Raiders' strategies|strategies]] when a raid event is spawned. Human raiders continue to attack until one of several conditions are met. Mechanoid raiders continue to attack indefinitely. Raiders who survive may return to attack again in future raids or ambushes. This includes prisoners abandoned from caravans who are in restraint, making them unable to attack properly.

<gallery widths="250px" heights="250px" class="center" mode="nolines">
File:Ransom.png|'''Ransom'''
File:Raiders Mod debuff tired and hungry.png|'''Raider's negative thoughts'''
File:Pirates have given up and area leaving.png|'''Pirates have given up and are leaving'''
Prisoner return as raider.png|'''Abandoned prisoner returns to ambush a caravan.'''
</gallery>

== Equipment ==
{{Rewrite|section=1|reason=1) Convert linked spreadsheet to wiki, and update as is many versions out of date. 2) Addiction drug carrying mechanics}}
[https://docs.google.com/spreadsheets/d/1pEhmCnRiBKAh5C7X6kHPSE7QKTeTRjspB-sHR2-B_os/edit?usp=sharing This Google Sheets spreadsheet] shows the spawn rates of weapons and apparel across all raider kinds. Valid as of 1.0.2057. Figures are taken from a modified version of the 'Pawn Kind Gear Sampled' dev tool with a sample size of 10,000 rather than 400.

=== Weapons ===
Raiders have limited equipment possibilities; dependent on their weapon and apparel budgets, and what equipment 'tags' they are allowed to equip. Usually on [[Cassandra Classic]] and [[Phoebe Chillax]] they come equipped early on with mostly [[autopistol]]s and crude melee weapons, some [[bolt-action rifle]]s and [[pump shotgun]]s later down the line. In the late game they can come equipped with things such as [[frag grenades]], [[sniper rifle]]s, [[incendiary launcher]]s and [[machine pistol]]s. Rarely some will have [[assault rifle]]s or [[LMG]]s.

A raiding party may include members equipped with melee weapons and [[shield belt]]s. When a raiding party includes grenade throwers, the AI is intelligent enough to run way from grenades thrown by their own faction (though this does not apply to other explosives). Raiders wielding rocket launchers will attempt to avoid friendly fire.

Counterintuitively, they can and will quite often spawn with melee weapons that result in them having a lower DPS than unarmed combat.

Also, raiders do not always use weapons appropriate to their skills, as the weapons are randomly chosen. They are often seen equipped with ranged weapons when they are better at melee (completely disregarding the [[Trait#Brawler|Brawler]] trait), and vice versa.

=== Armor ===
They come in different clothing depending on their type and the outside conditions. If it's cold at your colony, they will come wearing [[parka]]s and [[tuque]]s, but they don't usually wear [[duster]]s and [[cowboy hat]]s in the heat.

=== Loot ===
{{stub|section=1|reason=Is there always loot?}}
Raiders can spawn carrying additional items unrelated to their pawnkind and their combat role. These function as an additional reward for defeating the raid. These items spawn inside the inventories of some raiders and are dropped on their being [[downed]]. The type of loot depends on the faction the raider is from. Note that while drugs and resources do spawn as part of this loot, it is in addition to that spawned for addictions and siege construction.

The total [[market value]] of the loot is proportional to the [[raid points]] of the raid it spawns in. The loot may spawn on one raider or it may be distributed across several individuals. Note that the value does not increase after 4000 raid points.

{| class="wikitable"
|-
! Loot market value by Raid points
|-
|{{Graph:Chart|width = 400
|height = 200
|type = line
|xAxisTitle = Raid Points
|xAxisMin =
|xAxisMax =
|yAxisMin =
|yAxisMax =
|yAxisTitle = Value (Silver)
|legend = Legend
|x = 35, 100, 1000, 2000, 4000, 5000
|y1 = 8, 60, 250, 400, 500, 500
|y1Title = Mechanoids
|y2 = 15, 120, 500, 800, 1000, 1000
|y2Title = All Other Factions
}}
|}

The items that compose the loot vary and are themed to the faction performing the raid. The options are:
{| class="wikitable"
|-
! [[Mechanoid Hive]] !! [[Outlanders]] !! [[Tribals]] !! [[Pirates]] !! [[Empire]]{{RoyaltyIcon}} !! [[Traders guild]]{{OdysseyIcon}}
|-
| {{Icon List|Plasteel}}
{{Icon List|Component }}
| {{Icon List|Silver}}
{{Icon List|Medicine}}
{{Icon List|Component}}
{{Icon List|Packaged survival meal}}
{{Icon List|Neutroamine }}
| {{Icon List|Silver}}
{{Icon List|Jade}}
{{Icon List|Herbal medicine}}
{{Icon List|Pemmican}}
|{{Icon List|Silver}}
{{Icon List|Medicine}}
{{Icon List|Packaged survival meal}}
{{Icon List|Flake}}
{{Icon List|Yayo}}
{{Icon List|Go juice}}
{{Icon List|Wake up}}
{{Icon List|Smokeleaf}}
{{Icon List|Luciferium}}
| {{Icon List|Gold}}
{{Icon List|Glitterworld medicine}}
{{Icon List|Uranium}}
{{Icon List|Packaged survival meal}}
| {{Icon List|Silver}}
{{Icon List|Medicine}}
{{Icon List|Component}}
{{Icon List|Packaged survival meal}}
{{Icon List|Neutroamine}}
|}

[[Salvagers]]{{OdysseyIcon}} share the same loot table as [[Traders guild]], despite being referenced as pirates in-game.

== Human ==
There are multiple types of raiders in RimWorld, each with their own sets of equipment and budgets which the game uses to 'buy' their equipment. Similarly, the game 'buys' raiders by deducting the raiders' Combat Power rating from the amount of raid points.

Raider types are exclusive to their faction - mercenaries being exempt.

This note is temporary and needs to be processed normally.
As a result of experiments, it was found out how many raid points some entities generate
Devouver-250
Himera- 135
Gorehulk- 75
Shambler- 50
Fleshbeasts sinkhole- 800
Sightstealer- 140

=== Tribals ===
{{main|Tribes}}
Tribal fighters, weak but expendable. They never carry [[silver]] or [[medicine]]. They carry [[pemmican]] as food.
{{:Tribes/Pawns}}

=== Pirates ===
{{main|Pirates}}
These units are encountered most frequently in the early game, but you'll see these units throughout the game. All easily dispatched once you get armor and high-grade weapons.
{{:Pirates/Pawns}}

=== Outlanders ===
{{main|Outlanders}}
As friendly units, they show up in caravans or friendly reinforcements. Rough outlander unions will also send these to attack your colony in the early game.
{{:Outlanders/Pawns}}

=== Mercenaries ===
Elite units typically encountered from mid-game onwards. Joins the Outlanders or Pirates in their ranks.
{{:Mercenaries/Pawns}}

=== Spacer ===
{{main|Ancients}}
These people don't appear in normal raids but are found in [[ancient shrine]]s. This variety is always hostile to the player's faction.
{{:Ancients/Pawns}}

=== Empire ===
{{Royalty|section=1|No Category}}
{{Main|Empire}}
{{:Empire/Pawns}}

=== Cultist ===
{{Anomaly|section=1|No Category}}

A spooky siege raid, will summon [[fleshbeasts]] if you don't take them out quickly. About half of the enemies would need to be executed twice due to [[Death refusal]], so do not leave the fight early. Mortars and mechanoid seem effective.

The unit types are highthrall (equipped with [[Nerve spiker]]s), underthrall gunner (equipped with heavier guns) and underthrall grunt (Equipped with melee weapons).

{{:Horax cult/Pawns}}

== Mechanoid ==
{{main|Mechanoid}}

Mechanical enemies that neither feel pain nor seek cover.

{| {{STDT| c_01 text-center}}
! Pawn Type !! Image !! Combat Power !! Gear Health (%) !! Avg. Gear Quality !! Clothing Budget !! Weapon Budget !! Available Weapons !! Age Range !! Additional Info
|-
! [[Scyther]]
|[[{{Q|Scyther|Image}}|50px]] || 150 || 100 || - || - || - || '''Melee (Blades)''' || Any || - 
|-
! [[Lancer]]
|[[{{Q|Lancer|Image}}|50px]] || 180 || 100 || Normal || - || 9999 || '''[[Charge lance]]''' || Any || -
|-
! [[Centipede]]
|[[{{Q|Centipede|Image}}|50px]] || 400 || 100 || Normal || - || 9999 || '''[[Heavy charge blaster]]''', '''[[Inferno cannon]]''', '''[[Minigun]]''' || Any || -
|-
! [[Pikeman]]
|[[{{Q|Pikeman|Image}}|50px]] || 110 || 100 || Normal || - || 9999 || '''[[Needle gun]]''' || Any || -
|-
! [[Termite]]
|[[{{Q|Termite|Image}}|50px]] || 110 || 100 || Normal || - || 9999 || '''[[Thump cannon]]''' || Any || -
|-
! [[Militor]]
|[[{{Q|Militor|Image}}|50px]] || 45 || 100 || Normal || - || 9999 || '''[[Mini-shotgun]]''' || Any || -
|-
! [[Legionary]]
|[[{{Q|Legionary|Image}}|50px]] || 150 || 100 || Normal || - || 9999 || '''[[Needle gun]]''' || Any || -
|-
! [[Tesseron]]
|[[{{Q|Tesseron|Image}}|50px]] || 150 || 100 || Normal || - || 9999 || '''[[Beam graser]]''' || Any || -
|-
! [[Scorcher]]
|[[{{Q|Scorcher|Image}}|50px]] || 110 || 100 || Normal || - || 9999 || '''[[Mini-flameblaster]]''' || Any || -
|-
! [[Tunneler (Mechanoid)|Tunneler]]
|[[{{Q|Tunneler|Image}}|50px]] || 400 || 100 || Normal || - || 9999 || '''Melee (Power claws)''' || Any || -
|-
! [[Centurion]]
|[[{{Q|Centurion|Image}}|50px]] || 250 || 100 || Normal || - || 9999 || '''[[Charge blaster turret]]''' || Any || -
|-
! [[Diabolus]]
|[[{{Q|Diabolus|Image}}|50px]] || 600 || 100 || Normal || - || 9999 || '''[[Hellsphere cannon]]''' || Any || -
|-
! [[War queen]]
|[[{{Q|War queen|Image}}|50px]] || 600 || 100 || Normal || - || 9999 || '''[[Charge blaster turret]]''' || Any || -
|-
! [[Apocriton]]
|[[{{Q|Apocriton|Image}}|50px]] || 600 || 100 || Normal || - || 9999 || '''[[Toxic needle gun]]''' || Any || -
|-
! [[War urchin]]
|[[{{Q|War urchin|Image}}|50px]] || 75 || 100 || Normal || - || 9999 || '''[[Spiner]]''' || Any || -
|-
|}

=== Mechanoid cluster ===
{{main|Mechanoid cluster}}

Added in Royalty was the "Mechanoid Cluster" event, which may be associated with quests or drop on their own. During this event, a fleet of drop pods will land and deploy mechanoids, walls, turrets, and assorted buildings. These mechanoids will initially be dormant. They are eventually awakened by either the player attacking, a Proximity activator being tripped, or a Count-down activator finishing its count down.

== Raiders' strategies ==
The message from the event will detail how the raiders from the hostile faction will raid.

=== General Mechanics ===

=== Raider Targeting ===

Standard raiders, including humans and mechanoids, attack targets based on a rough priority system with some random elements. Raiders who are able to path towards a colonist or powered turret will attempt to attack such a colonist or pathable furniture. Raiders who are only able to path towards furniture may attack that furniture or may instead attack random walls and doors. The chance raiders attack the furniture rather than random walls and doors has some random elements to it. Raiders who cannot path towards any colonist nor any furniture targets will attack random walls and doors.

Pathable means that the raider can move to the same cell as the target. "Furniture" targets include objects like stools, tables, chairs, and even things like Wind Turbines, Geothermal Generators, Unpowered Turrets, and production benches.

Raider targeting can change based on nearby targets, if their target is destroyed or becomes non-pathable, or if they take damage.

Raider targeting can also be overridden by nearby targets of opportunity. Raiders may light wooden walls or crops on fire, for example.

=== "Victory" Conditions ===

Human raiders continue to attack until one of several conditions are met. Mechanoid raiders attack indefinitely. Once mechanoids have destroyed every possible target they wander around in place indefinitely until a new target appears.

Downing or killing 40% to 70% of human raiders causes the remaining alive raiders to cease their attack and attempt to flee. A random value between 40% and 70% is chosen for each raider group. If a raid attacks in multiple groups, each group has their own randomly chosen 40% to 70% flee value. Each individual raider group only counts dead or downed members of their own group. Each group attacks and flees independently.

Human Raiders will flee after attacking for approximately 10 to 15 hours. A random value is chosen between these timers. After the time is passed the group will flee. For enemies attacking in multiple groups, each group will have its own timer and solely that group will flee when the timer is met. For sieges, the timer only begins after the siege stops attempting to siege and directly assaults the colony.

Human enemies may attempt to kidnap downed colonists. When kidnapping, enemies may disengage from combat and attempt to flee the map.

Human enemies may attempt to steal nearby loot. When stealing, enemies may disengage from combat and attempt to flee the map. How much nearby loot is required to cause raider theft depends on the raid points of the colony. Higher raid points requires more loot.

{| {{STDT| c_50}}
! style="text-align:left;" | Map Entry || Attack Type || Smart? || Faction Raiders || Ally use this raid?
|-
| rowspan="7" | Walk in Edge (45%)
| rowspan="3" | Immediate Attack
| No
| rowspan="3" | Tribal, Outlander, Pirate, Mechanoid
| rowspan="2" | Yes
|-
| Yes
|-
| Yes (Breach)
| No
|-
| rowspan="2" | Preparation || No
| rowspan="7" | Tribal, Outlander, Pirate
| rowspan="2" | Yes
|-
| Yes
|-
| Sapper || No
| No
|-
| Siege || No
| Yes
|-
| rowspan="3" | Walk in Edge Group (15%)
| rowspan="2" | Immediate Attack
| No
| rowspan="2" | Yes
|-
| Yes
|-
| Sapper || No
| No
|-
| rowspan="7" | Drop pods (30%)
| rowspan="3" | Immediate Attack
| No
| rowspan="5" | Tribal, Outlander, Pirate, Empire, Mechanoid
| rowspan="2" | Yes
|-
| Yes
|-
| Yes (Breach)
| No
|-
| rowspan="2" | Preparation || No
| rowspan="2" | Yes
|-
| Yes
|-
| Sapper || No
| rowspan="2" | Tribal, Outlander, Pirate, Empire
| No
|-
| Siege || No
| rowspan="2" | Yes
|-
| Haywired drop pods (10%) || Immediate Attack || No || Tribal, Outlander, Pirate, Empire, Mechanoid
|-
| colspan="2" | Mechanoid Cluster {{RoyaltyIcon}} || No || Mechanoid || No
|}

=== Immediate attack ===
{{Quote|They are attacking immediately.|Description}}
Raiders, upon either landing in their drop pods or arriving on the map sides, will proceed to instantaneously converge on your colony and attack. The best thing to do is to defend.

=== "Drop right on top of you" drop pods ===
Raiders will drop pod right "on top of you" circumventing all exterior defenses. "Drop on top of you" raids choose a singular colonist and all drop pods land around this target in open cells. That singular colonist cannot be under overhead mountain. The drop pods can crash through nearby overhead mountain even though the singular colonist target cannot currently be under overhead mountain.

Only outlander, pirate and empire factions can "Drop right on top of you". Tribal factions cannot use drop pods. Mechanoid "Drop right on top of you" raids were removed in patch 1.4.

Rather than landing on a colonist, "Drop right on top of you" raids have a 40% chance to land on a powered, unroofed, orbital trade beacon.

These "drop right on top of you" raids always attack immediately and follow standard enemy pathing.

Since most raiders in this situation will use a ranged weapon, you can use the time between the last drop pod land and the first raider emerge to position melee fighter in between and prevent them from shooting.

=== Immediate attack smart ===
Like Immediate Attack, but the raiders are unusually clever in their tactics because they try to avoid turret line of sight if possible. If there is no path to the raider's target around turret line of sight, or if their target is a turret, they will walk through turret line of sight.

Despite their description, they do not avoid traps like Spike Traps nor IEDs in any way.

=== Preparation ===
Raiders, upon either landing in their drop pods or arriving on the map sides, will proceed to stand around in a small group near-by where they spawned for a period of time and then proceed to attack. It is possible and a completely viable strategy to attack them while they are "preparing". This preparation has no effect on their attack other than the fact that it gives you more time to prepare yourself.

=== Sappers ===
{{Quote|It looks like they want to use sappers to tunnel around your defenses.|Description}}
Instead of attempting to kill your colonists by traditional attack, sappers will mine or blast their way inside rather than hitting your walls or doors as usual. Their ultimate goal is an assigned constructed sleeping position. Freely placed sleeping spots, and unassigned beds do not qualify. An assigned sleeping position can be a colonist bed, an animal bed, or prisoner bed with a name on it rather than it being unassigned.

The attacker with the best mining skill is chosen to dig. If that digger is killed the next best digger continues digging, and so on.

They can be fairly dangerous to those who tunnel into mountains as their defenses are usually concentrated at the entrances. The best thing to do is instantly assault them before they can mine too much. The other members will then carry on the normal assault. They seem to avoid digging through high-health ore veins or into the areas within the range of improvised turrets and don't mind much about other security traps (spike trap and all kind of IEDs). It's possible to create such an trap area to kill them before hand.

However, in open bases they are even worse than regular raiders as they come in smaller numbers.

Sappers can find one tile defenses, either natural rock or built walls. This may cause them to open ancient shrines unintentionally.

<gallery mode="packed-hover">
File:Sappers are good at finding one tile walls.png|1: Sappers are good at finding one tile walls.
File:Sappers may even open ancient structures unwisely.png|2: Sappers may even open ancient shrines unwisely.
File:Sappers attacking ancient structures will kill spacers you would love to recruit.png|3: Sappers attacking ancient structures will kill spacers you would love to recruit.
File:Sappers may cause mechanoids to function as your outer defense line.png|4: Sappers may cause mechanoids to function as your outer defense line.
File:Sappers demise.png|5: Sappers are defeated.
</gallery>

=== Breachers ===
{{Quote|These raiders intend to breach your walls. They'll determine their own path into your colony and destroy anything in their way.|Description}}

Much like sappers, raiders will utilize their tools to easily breach past your walls. Breachers, like sappers, target assigned constructed sleeping positions. Unlike Sappers, however, breachers come equipped with tools designed to destroy walls easily regardless of their mining skill.
* [[Tribals]] use pawns equipped with [[breach axe]]s.
* [[Outlanders]], [[Pirates]], and [[Empire|Imperials]]{{RoyaltyIcon}} use [[frag grenade|frag grenadiers]].
* Mechanoids utilize the [[thump cannon]]-wielding [[Termite]].

Unlike sappers, they mostly target colony-built walls in their direct path, instead of mining the shortest route. Any raiding pawns nearby will always follow the breaching pawn in question, only attacking within range. Breachers will not attack passable player buildings, and instead only target impassable buildings like walls.

They ignore walls that are not owned by the colonist unless there are no pathways around them, making it more difficult to trick the breachers into unintentionally opening the ancient shrines.

There are two types of Breach Raids: Standard breach raids which ignore turrets and "Smart" breachers which attempt to avoid turret line of sight. The "Smart" Breach Raid letter will contain the phrase "they appear unusually clever with their tactics. They'll avoid your turrets' fields of fire and notice some of your traps". Smart breachers do not actually notice any of your traps. Smart breachers only may attempt to avoid turret line of sight if possible.

[[File:Siege base construct.png|350px|thumb|right|Siegers arriving at their chosen minibase location. The faint "blueprint" for the base is not visible until the resources are dropped.]] [[File:Siege_base_finished.png|350px|thumb|right|Siegers done constructing their minibase and questionable defenses, moving toward commencing bombardment.]]

=== Siege ===
{{See also|Auto-mortar}}
{{Quote|It looks like they want to besiege the colony and pound you with mortars from a distance. You can try to wait it out - or go get them.|Description}}

Raiders enter your map from an edge and head towards a point well outside your base to set up a makeshift siege base. Once there, drop pods supply them with ample resources to construct 2 [[mortar]]s ([[steel]], [[component]]s, and both [[high-explosive shell]]s and [[incendiary shell]]s). They also get some [[cloth]] to create [[sandbags]] as cover, and [[packaged survival meal]]s. Two random raiders will begin constructing the mortars (one each), and a few more will throw the sandbags down while the rest stand guard.

You can engage them before they finish building up if timing is favorable to you. They will always attempt to construct only two mortars regardless of the number of raiders. The layout of the mortar base is somewhat random - they might decide to place a mortar where some trees need cutting first, slowing the process considerably, and the sandbags are rarely well placed. The siegers rarely use their best constructors when building (it's random), so sometimes fail the [[construction]] process and waste that mortar's resources. As they will not get additional components, this will make any bombardment half as damaging.
[[File:Passive siegers.png|200px|thumb|left|Siegers not engaging friendlies while traveling to set up base.]]
Once a mortar is ready, they will start to bombard you, guarded by those not busy manning the mortars or still building the second one. Drop pods will continuously resupply 12 packaged survival meals and more mortar shells, as needed. When they run low on [[mortar shell]]s they will receive random resupplies of high explosive or incendiary shells only. After causing enough destruction, they will proceed as a normal raid to converge on your colony. Valid targets appear to be colonists and buildings but not player owned animals.

The siege team will not engage friendlies while heading towards their future base until they actually start constructing or you assault them first.

A siege will begin their direct assault of the player colony under a few conditions. The siege will begin their assault after a random amount of time between 1.5 and 3 days has past. Every time a sieger takes damage there's an 8% chance the siege assaults directly.

=== Ambush ===
Raiders may choose to attack one of your caravans. In this case, they will charge right at your caravan without giving a second thought to strategy.

=== Multiple group attacks ===
Enemies can split up their attacking forces, attacking using multiple groups at once. Each group attacks from a different direction, and flees on their own accord.

=== Drop pod scatter ===
Enemies capable of drop pods have a chance of launching a raiding party onto the map via said pods at random points scattered around the map. Due to the fact they can drop through roofs, this type of attack can be incredibly devastating, as they can bypass all of your external defenses and immediately start setting fires, attacking colonists, and destroying furniture. The layout of your base and the room they choose to drop in can also make it very difficult to set up a sufficient defense, as they may drop into an extremely unfortunate location, such as a cramped storage room with lots of things to burn and destroy, and no good way to attack them beyond filing all of your fighting colonists into the room and hoping for the best or attempting to shoot through the door. While the raiders themselves will most likely be easy enough to kill, it is likely they will have ample opportunity to cause tons of damage before they can be stopped. Setting up ample fire defenses and having a defense plan for all potential drop points can help limit the amount of damage they can cause, although it’s almost guaranteed they will be able to cause at least some damage if they drop directly into a room.

===Emerge from water===
{{Stub|section=1|reason=Added in 1.5}}
Mechanoids can emerge from bodies of water (shallow ocean water, shallow moving water, chest-deep moving water) to attack your colony.

=== Weapon-specific raids ===
Human raiders have the ability to send raiders with a specific kind of weapon only.

==== Melee rush ====
Pirate or outlander raiders have the chance to attack your base with mercenary slashers only, meaning everyone will be shielded and have a melee weapon. Tribals can do the same with their melee units, except without shields.

Mechanoids have their own rendition of the melee rush with [[scyther]]s only.

==== Sniper party ====
Pirates or outlanders have a chance to send snipers only, meaning that all attackers will have long-ranged attacks.

==== Explosives assault ====
Pirates or outlanders have the chance to send a party consisting of either grenadiers or heavy mercenaries. While this makes them extremely destructive, it also makes them particularly prone to friendly fire.

== Raid strength ==
{{Main|Raid points}}
A raid's size and strength is determined by the amount of colonists you have, your wealth, how many big threats you've had (for the early-game), how long your faction's been around for, how long it's been since one of your colonists were downed or killed, and your difficulty.

The actual raid strength is determined by points, which is calculated by taking into account the above factors that affect raid strength.

For a full technical breakdown; see [[Raid points]]


== Defense strategies ==
{{Move|reason=Move non-raid strategy sections to their respective pages. e.g. scyther recommendations to [[scyther]] tribal recommendations to [[Tribes]].|destination= Scyther{{!}}Scyther etc.}}
''For a more comprehensive list of strategies, see [[Defense tactics]].'' <br>
''For constructed defenses to hold against raiders, see [[Defense structures]].''

It is recommended to keep power generation, eating areas, lighting, doors, and walls near or behind a protected entrance, as raiders tend to set fire to them, potentially causing huge damage. Raiders will prioritize firing on colonists or turrets when those colonists or turrets are firing on them, but will otherwise prioritize random objects, meaning you can put doors or walls near your defenses to temporarily distract them.

=== Raider preparation ===
Raiders will sometimes start by standing around in a group where they spawned and will continue this until they see a [[colonist]] nearby or they hit a certain preparation time limit, at which point they begin the assault. Because a colonist can set them off early, you can plan out the time you want them to attack. It is generally best to set them off early if you're well-prepared, to avoid potentially troublesome scenarios such as having no power when their timer runs out. Conversely, you should not set them off early if your defense is not prepared. Note that raiders usually take less than one day to begin, meaning that if there is an eclipse and you rely on [[Buildings#Solar generator|solar generators]], you should not wait for them and should instead set them off early while you still have some power left.

=== Siege defense ===
When faced with a siege, there are a few coping strategies you can use.

You can choose to either assault the mortar base or wait it out and repair the damage as best as you can. The choice mainly depends on the surroundings of the mortar base and your base's position. If your base is located under a mountain (your base tiles will read ''Overhead Mountain'' when you hover your cursor over them), the mortar shells won't be able to hit those tiles at all! This makes deep mining a very effective strategy against heavy bombardment. If you don't build your base into a mountain, you should at least consider digging out at least one panic room for your colonists to hide within from the shells.

If you assault their base, one possibility is sniping either the shells or the mortars, hoping an explosion kills many of the raiders. If you want to leave those intact, you can snipe the raiders themselves. Keep in mind that killing enough of them prompts them to assault your colony directly instead of continuing their siege.

=== Mechanoid assaults ===
Mechanoids have much differing stats and weapons, meaning different tactics may be used.

In most raids where they come/ drop in at the edges, the scythers will outrun the centipedes by a great margin, giving plenty of time to deal with them before the centipedes.

==== Lancers ====
Lancers are capable of mid-long range high damage attacks. If fighting it from a distance, cover along with mid-long ranged weapons such as [[assault rifle]]s or [[bolt-action rifle]]s are vital.

Due to the lancers' weak melee ability and low health, melee fighting it is always the better choice.

==== Scyther ====
Scythers are dangerous melee fighters; they deal significant melee damage while forcing your gunners into melee combat. Usually, a 1v1 fight with a scyther and a gunner will result in the scyther emerging victorious.

Melee fighters are useful in guarding against scythers, being able to 'peel' them off from more vulnerable allies. A thrumbo could beat up one easily, they are strong enough that even a calf could kill one in a 1v1.

==== Pikemen ====
Pikemen can snipe your colonists from a very long distance, though their damage output is abysmal.

Due to the pikemen's weak melee ability and low health, melee fighting it is always the better choice.

==== Centipedes ====
Centipedes, on the other hand, specialize in crowd control and area denial; the [[minigun]] and [[heavy charge blaster]] can annihilate groups of colonists, while the [[inferno cannon]] sets your colonists ablaze and burns down your base if not careful. They are incredibly durable, sporting thick armor and high health, and can take many hits before they can be downed.

The inferno cannon is not as directly destructive towards your colonists, but is dangerous due to the [[fire]] it spreads - destroying defenses and bases, causing burning pawns to run out of cover, and preventing movement. Keep watch on your colonists at all times, and remember to send them back into cover when needed. As a precaution, build your base out of non-flammable materials to prevent large-scale fires erupting all over your colony.

Centipedes engaged in melee cannot employ their heavy weapons. Their melee is hard hitting and effective against armor, but very slow, making it easy to overwhelm them with multiple melee attackers. One of the fastest ways to eliminate one is by employing upgraded [[ghoul]]s{{AnomalyIcon}} or [[melee specialist]]s{{IdeologyIcon}} with [[monosword]]s{{RoyaltyIcon}} and [[zeushammer]]s,{{RoyaltyIcon}} but even Core-only melee pawns with [[uranium]] [[mace]]s and decent armor will be effective.

=== Tribal raids ===
Tribal raiders come in large numbers, but with relatively poor equipment; as such, it may require different strategy compared to pirate or outlander raids.

Overall, they can deal heavy damage to your colonists; they do not have good weapons, but compensate with their sheer numbers. <br>
However, as tribalwear does not provide protection and they do not wear any form of regular armor, they are easier to kill individually than other raiders.

Crowd control is an important aspect in defeating tribal raids. The [[minigun]] or [[LMG]] is an effective weapon to use as it can easily mow down groups of raiders.

Explosive weapons are also useful in crowd control.

Explosive mortars, while inaccurate, can easily destroy a sizable group of tribals at once if they hit. <br>
Grenades can hit archers hiding behind cover, though you have to risk a colonist or two in order to even get close enough to throw them. <br>

Their archers are dangerous; their bows can be fired from a somewhat long distance, their pila can easily kill or incapacitate a colonist, and they always come in a large volley. As with most defensive strategies, cover is essential when fighting them.

Removing rock chunks also helps in dealing with tribal raiders hiding behind them, making them much easier to hit.

== Version history ==
* [[Version/0.0.245|0.0.245]] - Sniper squad and mercenary squad added.
* [[Version/0.3.410|0.3.410]] - Raiders come from specific factions and don’t always drop from orbit. Tribal raiders now spawn and attack.
* [[Version/0.5.492|0.5.492]] - Sieges added.
* [[Version/0.11.877|0.11.877]] - Sappers added. Raiders now opportunistically ignite crops on fire.
** A11B - Siegers can never use melee weapons. Enemies (especially wargs) now ignore unpowered unmanned turrets and mortars.
* [[Version/0.12.906|0.12.906]] - Sappers now avoid mining through high-health ores and barriers. Siegers will never be sent with only melee weapons ... again?
* Beta 19/ 1.0 - Heavily reworked the selection weights of raider factions, raider strategies (sappers, siege, etc) and arrival modes (walk-in, drop pods) to make the more difficult ones appear more consistently against stronger colonies.
* [[Version/1.3.3066|1.3.3066]] - Added new raid type: Breaching. Breaching raids will attempt to reach your colony by breaking through walls with unique weapons.
* [[Version/1.3.3159|1.3.3159]] - Reduce prevalence of breach raids at high points levels.
* [[Version/1.3.3200|1.3.3200]] - Adjusted human factions' raid strategy selection weights for slightly more variation. Breachers no longer want to attack passable player buildings. They only target impassable buildings like walls.
* [[Version/1.4.3524|1.4.3524]] - Fix: Breach raids not spawning.
* [[Version/1.4.3527|1.4.3527]] - Fix: Hostile pawns try to path to destroyed structures.
* [[Version/1.5.4062|1.5.4062]] - Mechanoids can now emerge from bodies of water to attack your colony.

{{nav|factions|wide}}
[[Category:Characters]]

Orbital mech cluster targeter

2026-02-15T20:22:45Z

Aelanna: Verified that mech cluster targeters can absolutely spawn in regular ADs with only Core and Royalty active. Screenshot proof in Discord.

{{Royalty}}
{{Infobox main
| name = Orbital mech cluster targeter
| image = OrbitalMechClusterTargeter.png
| description =An ancient military targeting device. It signals an orbital platform to drop a mechanoid combat cluster at the targeted point. The cluster may include any mixture of mechanoids and mech defense structures.<Br>Though they may have once had some allegiance to the ancient army that created this unit, any mechs dropped now will indiscriminately attack any human they see - including the one that summoned them.<Br>The unit only contains one usage code, so it can only be used once.
| type = Gear
| type2 = Utility
| tech level = Spacer
| marketvalue = 1200
| hp = 100
| flammability = 0.5
| mass base = 0.2
| lifestage = Adult
| clothing for nudity = False
| coverage = Waist
| layer = Belt
| tradeTags = ExoticMisc
| thingSetMakerTags = SingleUseWeapon
}}
The '''Orbital mech cluster targeter''' is a powerful single-use [[utility]] item that calls a [[mechanoid cluster]] down on the targeted location. These [[mechanoids]] are not allied to the user in any way, and behave as normal mechanoids do.

== Acquisition ==
Orbital mech cluster targeters cannot be crafted, acquired through trade, or from quests. They can only be found in [[ancient shrine]]s and [[Hermetic_crate|Odyssey ruin hermetic crates]]{{OdysseyIcon}}.

== Summary ==
{{Stub|section=1|reason=More detail needed inc. What point value do they use? Are they always the same size or do they scale with [[raid points]]?}}
When equipped, an orbital mech cluster targeter is worn in the waist [[Utility|utility slot]]. Pawns that are incapable of violence can equip, but not use, the targeter. Once the wearer is [[draft]]ed, it can be manually activated by the player to target a tile within 45 tiles and within [[line of sight]]. It can be targeted under roofs of all types but pods landing on overhead mountain will cause cave-ins and create [[collapsed rocks]], destroying the pod and its occupants in the process.

After a 3s warm-up, a [[mechanoid cluster]] will spawn in the targeted area. The warmup time before firing is affected by the [[Aiming Time]] stat of the wearer. This cluster is identical to other clusters but will never spawn with a [[condition causer]]. The [[mechanoids]] within are not allied to the user in any way, and behave as normal mechanoids do. They will be hostile to everyone except other mechanoids.

The targeter cannot be recharged or refueled - once its single charge is expended, the item is completely destroyed.

{{Utility Note}}

== Analysis ==
{{Stub|section=1|reason=Essentially missing analysis}}
They are in every way a mech cluster you can summon, with all the help and hindrance that can bring. Use with caution and remember it does not help against other mechanoids.

== Version history ==
* [[Royalty DLC]] Release - Added.
* [[Version/1.2.2719|1.2.2719]] - Will no longer spawn a cluster with [[condition causer]].
* [[Version/1.2.2753|1.2.2753]] - New artwork for orbital targeters. Changed from a Weapon to a Utility item. Prior to this, like all ranged weapons it couldn't be used when the pawn was wearing a [[shield belt]].
<gallery>
OrbitalTargeter.png|Old generic targeter sprite
</gallery>

{{Nav|utility|wide}}
[[Category:Utility]]

Patchleather

2026-02-15T17:52:30Z

Aelanna: Spelling, capitalization

{{Infobox main|leathery
| name = Patchleather
| image = Patchleather b.png
| description = A weak textile created by cutting up and sewing together various types of leathers. Regardless of what kind of leather is used to create it, patchleather's irregular seams make it less tough and less insulating than any intact leather.

| type = Textile
| type2 = Leather
| stuff category = Leathery
| hp = 60
| flammability = 1
| marketvalue = 1.5
| beauty = -30
| mass = 0.03
| stack limit = 75
| path cost = 14

| beauty factor = 1
| work to make factor = 1
| work to build factor = 1
| max hit points factor = 1
| flammability factor = 1
| armor - sharp factor = 0.45
| armor - blunt factor = 0.19
| armor - heat factor = 0.9
| insulation - cold factor = 9
| insulation - heat factor = 9

| production facility 1 = Hand tailor bench
| production facility 2 = Electric tailor bench
| work to make = 900
| resource 1 = Stuff
| resource 1 amount = 50
| stuff tags = Leathery
| product amount = 50

| page verified for version = 1.2.2753

| color = (90,75,60)
| commonality = 0.0025
| default color = (90,75,60)
| label = patchleather
}}
{{Info|'''Patchleather''' is a type of [[leather]] produced when a [[Skills#Crafting|tailor]] combines different types of leather at a [[electric tailor bench|tailor bench]]. Useful for combining unusably small amounts of different leathers into a single type to get a large enough quantity for use.}}

== Acquisition ==
Unlike other leathers, patchleather is not procured by butchering animals, but rather by combining other leathers together at a [[electric tailor bench|tailor bench]]. 50 units of any other types of leather, except [[human leather]],{{Check Tag|Dreadleather?|Dreadleather has similar penalties - does it prevent its use? Even if no, specify that it is allowed}} will output 50 units of patchleather.

== Usage ==
{{PAGENAME}} can be used as a material for [[stuff]]able items with the [[Leathery]] stuff tag.

{{PAGENAME}} can be used in the following recipes:
{{Ingredient List}}

== Analysis ==
Patchleather has the worst stats of any leather in the game in both protection and insulation. The only [[textiles]] it is superior to in protection are [[cloth]] and the [[wools]], and even then, just barely. Meanwhile, patchleather is significantly inferior to both cloth and wools in terms of temperature insulation. It has the lowest insulation, market value and beauty of any textile, and tied for the 2nd lowest item hitpoints.

The main advantage of patchleather is that it's easy to produce in bulk. Small quantities of different leathers are insufficient to make anything on their own. Converting them to patchleather will turn said unusable resource into a usable one. Keep in mind, however, that it may be more profitable to sell the other leathers directly, rather than create objects out of patchleather.

Generally, it should only be when there is no alternative, where its stats have little effect on the utility of the resulting item or maintain lower [[wealth]] for min-maxing runs.
few useful uses are:
* Clothing production [[quests]] where material and value don't matter, only quality.
* [[Armchair]]s/[[couch]]s in rooms where [[beauty]] isn't important for the [[room stats|room's quality]].
* Prisoners and Slaves clothing for lower defense and wealth values in case of prison breaks and slave rebellion.
* [[Heavy bandolier]] the [[Ranged Cooldown Multiplier]] passive is not affect material while it's cheaper
* [[Bedroll]]s for caravans [[Rest]] and [[Comfort]] will remain the same while it's cheaper

== Gallery ==
<gallery>
Patchleather a.png|One patchleather
Patchleather b.png|Stack of patchleathers
</gallery>

== Version history ==
* [[Version/0.19.2009|0.19.2009]] - Added.
* [[Version/1.2.2753|1.2.2753]] - [[Quests|Trade requests]] will no longer request patchleather.

{{Nav|materials|wide}}
[[Category:Material]] [[Category:Textile]] [[Category:Leather]]

Toxic wastepack

2026-02-10T03:54:10Z

Aelanna: Dug into the mechanic a bit further with some assistance from a dev.

{{Biotech}}
{{Stub|reason=1) 1.4.3555 impacts for dumping. Analysis, inc. whenever they are worth disposing at all 2) Type }}
{{Infobox main
| name = Toxic wastepack
| image = Wastepack_a.png
| type =
| tech level =
| description = A compacted package of toxic waste that will slowly dissolve if not frozen. The surface is heat-sealed for safe transport. Wastepacks will pollute the surrounding terrain if they dissolve, deteriorate, or are otherwise destroyed. Toxic wastepacks are flammable. If burned or damaged, they will release tox gas.
| mass base = 6
| stack limit = 5
| hp = 100
| beauty = -40
| flammability = 1
| deterioration = 4
| marketvalue = 0
| defName = Wastepack
| thingCategories = ItemsMisc
| page verified for version =
}}
'''Toxic wastepacks''' are waste products created by mech-related buildings or the cleanup of [[polluted]] tiles.

== Acquisition ==
[[Pollution pump]]s and pawns manually cleaning [[pollution]] on the ground will generate wastepacks, at a rate of 1 wastepack per 6 polluted tiles. Wastepacks may also be dropped into your colony as part of a [[Quests#Wastepack_Dumping|quest]].

===Mechanoid Recharging and Gestation===
Toxic wastepacks are produced when [[friendly mechanoids]] utilize [[mech recharger]]s or [[large mech recharger]]s, or whenever a [[mech gestator]] or [[large mech gestator]] finishes gestating one. The amount of wastepacks produced is proportional to the Bandwidth of the mech recharged or gestated.
{{Mech Bandwidth}}

== Summary ==
Up to 5 toxic wastepacks can fit into 1 tile, and they do not fit on [[shelf|shelves]].

===Pollution===
When a wastepack is destroyed in any fashion, they will [[pollution|pollute]] 6 ground tiles of a colony, per wastepack. A full stack of 5 wastepacks pollutes 30 tiles. This pollution can spread through constructed [[wall]]s, but will not bypass natural stone walls.

When burned or damaged, wastepacks release [[tox gas]], in addition to the pollution.

When dumped from a [[caravan]], a caravan that is carrying them is destroyed, or sent via unmanned [[transport pod]], wastepacks will lower the [[goodwill]] of whatever faction has a faction base closest to the tile the wastepacks were dumped at, regardless of how far away that base is. The goodwill loss is proportional to the amount of waste dumped and its proximity to any nearby faction bases, ranging from {{--|1}} goodwill for just a few packs nearby up to {{--|60}} or more for multiple filled pods dumped directly on a base. Wastepacks dumped on the world map immediately pollute the world tile by 0.05%, requiring 2000 wastepacks to completely pollute a hex from 0% to 100%.

If dumped in [[Orbit]]{{OdysseyIcon}}, wastepacks use the same proximity calculations as they do on the ground except that as the [[Traders guild]] is the only faction in orbit, they will always be the faction angered. Wastepacks dumped in orbit also will not result in tile pollution or affect the planet below.

If the angered faction is hostile (including those made hostile by the wastepack dump), they may decide to retaliate. The percentage probability of retaliation is equal to the goodwill lost by the wastepack dump. Factions (except [[tribes]]) may retaliate by dropping wastepacks back at you, and hostile factions of any kind may send a [[raid]] in response to your "gifts". Factions will randomly select (with equal probability) between the available responses, and the response will arrive after a random delay of one to three days. Multiple wastepack pod salvos done in short succession may result in back-to-back or even simultaneous raids. Both forms of retaliation are announced upon arrival with a "Pollution retaliation" letter.

===Dissolving===
1 wastepack per stack will dissolve every 8 days, with the following factors:
* 0.5x if indoors.
* 2x if in [[Weather|rain]] and outdoors, even if [[roof]]ed.
* 0x if {{Temperature|0}} or lower. Any temperature above freezing point will not slow the dissolving of the wastepack.

The packs also deteriorate in the same way as all other items. As an example, 5 Toxic wastepacks left out in the rain will dissolve 1 wastepack after 4 days and deteriorate the rest over the course of the next day or so as they lose HP at a rate of 20 per day outside in the rain. This means that even if temperature is below freezing when left outside or unroofed, a wastepack will slowly lose HP and eventually be destroyed, releasing the pollution inside. Unlike most other items, deterioration leaves behind the pollution inside rather than deleting the item altogether.

===Gravship===
{{Odyssey|section=1}}
Unique to wastepacks, [[Gravship]]s cannot land on tiles occupied by them. When a wastepack dissolves on a tile occupied by a gravship hull the pollution will remain on the underlying and not within the gravship.

== Analysis ==
===Storage===
A 7x7 room holds 245 wastepacks, and can be cooled by a single [[cooler]] in a double-walled room, and is effective up to an outside temperature of {{Temperature|41}}. 245 wastepacks are enough storage:
* To constantly run 8 [[bandwidth]] worth of [[mechanoids]] for 1 entire year, 4 bandwidth of mechs for 2 years...
* To store the waste of 2 [[toxifier generator]]s for ''6 years''. A [[pollution pump]], or a pawn cleaning the pollution by hand, is required to turn ground pollution into wastepacks.
Depending on [[biome|climate]] and freezer setup, you can get more storage with 1 cooler. And this is 1 cooler - worth {{Required Resources|Cooler}} and {{Q|Cooler|Power Consumption}} W of [[power]] (plus the material for [[wall]]s and [[door]]s). You can easily use multiple coolers to store your waste. This gives you enough time to get a form of waste disposal ready.

===Disposal===
[[File:Wastepack disposal by shuttle.jpg|thumb|400px|right|<small>An Empire shuttle full of wastepacks. credit to /u/BenightedAlizar on r/rimworld</small>]]
Most means of destroying wastepacks have some sort of consequence:

* '''Letting it pollute.''' Pollution is localized - wastepacks that deteriorate or dissolve away from your base won't have an impact, at least for a while. [[Insectoid]]s may come as wastepacks are destroyed, and [[acidic smog]] can happen at high enough pollution levels.
* '''Dumping it offsite.''' Dumping will always incur a goodwill loss for a single faction based on the current relationship status, distance from the nearest [[faction base]] and number of wastepacks dumped. You will receive significantly larger penalties for dumping closest to allies than for dumping closest to hostile or neutral factions (e.g 1 wastepack dumped directly on a hostile will give -1 goodwill but if dumped on an ally it will give -12 goodwill). {{Check Tag|Odyssey|What about leaving the wastepacks behind when leaving in the gravship?}}

You will always get at least -1 goodwill for dumping wastepacks. Even if you are situated on one pole of a 100% generated world and the nearest faction base is on the opposite pole and you dump a single wastepack one tile away from your base you will still receive a -1 penalty.

{| class="wikitable"
! Faction status !! Dumping distances in tiles !! Goodwill lost (25 wastepacks)
|-
| Allied || 0 || 31
|-
| Allied || 1 || 15
|-
| Allied || 2 - 4 || 6
|-
| Allied || 5 - 16 || 2
|-
| Allied || 17+ || 1
|-
| Neutral || 0 || 25
|-
| Neutral || 1 || 12
|-
| Neutral || 2 - 5 || 5
|-
| Neutral || 6 - 18 || 2
|-
| Neutral || 19+ || 1
|-
| Hostile || 0 || 25
|-
| Hostile || 1 || 12
|-
| Hostile || 2 - 4 || 5
|-
| Hostile || 5 - 16 || 2
|-
| Hostile || 17+ || 1
|}

Wastepacks may also be dropped back at you, and if the faction is already hostile, you may start a [[raid]]. Dumping within 4 tiles of your colony will increase the chance for acidic smog.
** '''[[Caravan]]s''' take time and food to set up, and have a limited carrying capacity - especially without [[pack animal]]s or [[friendly mechanoids]].
** '''[[Transport pod]]s''' can dump wastepacks far away. 1 pod, which can store up to 25 wastepacks, and per launch costs {{Required Resources|Transport pod}}, and a variable amount of {{Icon Small|chemfuel}} [[chemfuel]] depending on how far you launch it.
** '''[[Imperial shuttle]]s''' {{RoyaltyIcon}} store up to 333 wastepacks (2000 kg) at a time, and simply transporting waste will not anger the [[Empire]] - dumping it has the usual penalties. This costs 1 permit slot, has a cooldown of 40 days, and requires a [[noble]] pawn of at least Knight/Dame rank. This permit can theoretically support up to 5 bandwidth without honor costs (although the realistic value is slightly smaller).
* '''[[Wastepack atomizer]]s''' have no direct consequences from their use. However, they require a precious [[nano structuring chip]] to create, a fair amount of [[power]], and aren't fast. One atomizer can support 4.8 [[bandwidth]] of mechanoids - a [[mechanitor]] is very likely to have more.
* '''[[Polux tree]]s''', which are another clean form of pollution removal. These trees only grow naturally if there is plenty of pollution already, though [[polux seed|seeds]] can be bought from traders. They clean only 20% as fast as a [[Wastepack atomizer]], and can only clean if there is no artificial buildings in the area, but will erase [[pollution]] directly from the ground. This is also a downside for dealing with future pollution, as these trees do not stop wastepack infestations.

[[File:Diabolus killing drop pods.png|thumb|336px|right|Diabolus destroying wastepack pods]]
When a landed [[transport pod]] is destroyed, its contents are vanished, which allows you:

* '''Bomb landed transport pods''', which exploitatively deletes wastepacks carried in them, leaving only [[steel slag chunk]]s and no pollution. Each pod can load 25 wastepacks. However this method costs a lot of [[steel]]s and [[component]]s to operate.
** While pods drop scattered around the target position, they always drop in the chosen, enclosed room.
** The most reliable way to destroy landed transport pods is the [[hellsphere cannon]] of a [[Diabolus]], which can destroy 25 pods and 625 wastepacks in one hit.

A pawn can be ordered to carry any chosen item by forming caravans. Additionally, by exploitatively forming caravans, a pawn can carry in its inventory up to the total colony carrying capacity, allows rapidly disposing wastepacks. This enables the following methods:

* '''[[Death acidifier]]s''', which exploitatively deletes wastepacks carried on a pawn with the implant on death. This does not cause pollution.
* '''[[Subcore ripscanner]]s''', which exploitatively locks wastepacks carried on a pawn on death. The pawn's corpse can then be destroyed along with any wastepacks in its inventory. This does not cause pollution.
* '''Pollute the [[undercave]]'''{{AnomalyIcon}}, which also helps you deal with [[fleshbeast]]s since they are not immune to [[toxic buildup]]. Pollution of the undercave does not pollute your colony in any way, and they cease to exist once its associated [[pit gate]] collapsed.
** Note once the polluted tiles reach the Dreadmeld's room, it will slowly die of toxic buildup, triggering the cave to collapse as normal when it does.
* '''Pollute the [[labyrinth]]'''{{AnomalyIcon}}, but you must destroy all wastepacks there, or the [[warped obelisk]] will teleport them back to your colony when you leave there.
* '''Pollute the [[metal hell]]'''{{AnomalyIcon}}, wastepacks dropped there do not come back with your pawns.
* '''Pollute [[Quests#Ancient_Stockpile|Ancient Stockpile]]'''{{OdysseyIcon}}, for all the advantages of polluting the undercave, indefinitely.
{{clear}}

== Gallery ==
<gallery>
File:Wastepack_a.png
File:Wastepack_b.png
File:Wastepack_c.png
</gallery>

== Version history ==
* [[Biotech DLC]] Release - Added.
* [[Version/1.4.3528|1.4.3528]] - Fix: Letting a pawn die on the world map with wastepacks will not pollute terrain.
* [[Version/1.4.3542|1.4.3542]] - Fix: Can destroy wastepacks on temp tiles to avoid relationship penalty loss.
* [[Version/1.4.3555|1.4.3555]] - Added more consequences for dumping near a [[faction base]].

{{Biotech navbox}}

Subcore softscanner

2026-02-01T21:42:18Z

Aelanna: General cleanup, reduction of the use of the term pawn, and spelling fixes.

{{Biotech}}
{{Infobox main|building
| name = Subcore softscanner
| image = SubcoreSoftscanner north.png
| description = A pod with thousands of tiny tissue probes and a high-energy brain scanner. Once a person is inserted, the system uses the probes and scanner to sense a neuro-psychic pattern that it can analog-transfer to a new standard-tier mechanoid subcore. The person will be left temporarily sick, but unharmed.<br>Subcores are mechanoid brains and producing any mechanoid requires one. Standard-tier subcores produced by this softscanner can only power standard-tier mechanoids.<br>Higher tier subcores can be created by building a subcore ripscanner.
| type = Building
| type2 = Biotech (Buildings)
| placeable =
| path cost =
| passability = pass through only
| blockswind =
| mass base = 25
| cover = 0.3
| minifiable = false
| size = 2x3
| flammability = 0.5
| hp = 250
| beauty = 0
| power = 150
| terrain affordance = Light
| research = Standard mechtech
| skill 1 = Construction
| skill 1 level = 5
| work to make = 8000
| resource 1 = Steel
| resource 1 amount = 200
| resource 2 = Plasteel
| resource 2 amount = 50
| resource 3 = Component
| resource 3 amount = 4
| thingCategories =
| room role = Laboratory
}}
The '''subcore softscanner''' is a building added by the [[Biotech DLC]] that allows for the creation of [[standard subcore]]s by scanning [[human]] minds.

== Acquisition ==
{{Acquisition}}

== Summary ==
The subcore softscanner takes 150 W of [[power]]. Its only purpose is to produce a [[standard subcore]], which is an ingredient used in the gestation of the following mechanoids:
{{Ingredient List|Standard subcore|noCollapse=1}}

A standard subcore requires {{Icon Small|Steel}} 50 [[Steel]] and {{Icon Small|Component}} 4 [[Component|Components]] to produce. Any [[human]] without scanning sickness can be selected for scanning by using the "Insert Person" button when selecting the subcore softscanner building. Upon selection, colonists and slaves will walk to the scanner if able, however prisoners or downed persons must be carried to the building by someone else. The scanning process takes {{Ticks|7500}} and inflicts scanning sickness upon completion.

=== Scanning sickness ===
<onlyinclude>{{quote|"This person was scanned by a softscanner to produce a mechanoid subcore. The high-energy scanning device has caused disturbances in their brain chemistry which will take time to resolve themselves. There won't be any long-term damage."|In-game description}}
A person scanned in a [[subcore softscanner]] to produce a [[standard subcore]] is afflicted with scanning sickness starting with a severity of 4 and decreasing in severity by 1 per in-game day for non-mechanitor pawns and severity decreasing by 2 per day for [[mechanitor]] pawns. This has the following effects:
* [[Consciousness]]: {{Bad|x75%}} (Post factors)
* [[Manipulation]]: {{Bad|x75%}} (Post factors)
* [[Moving]]: {{Bad|x75%}} (Post factors)
* [[Vomiting]] {{MTB}}: {{Bad|1.5 days}}
* [[Mood]]: {{--|8}}</onlyinclude>

== Analysis ==
Scanning sickness reduces a colonist's [[consciousness]], [[moving]], and [[manipulation]] by 25% for four in-game days, which results in a severe reduction in productivity. As such, [[prisoner]]s are ideal candidates for scanning as they cannot do work anyways.

Standard subcores are used in the gestation of a variety of useful mech types, such as [[tunneler]]s for mining ore deposits or [[scyther]]s for general melee combat. The softscanner is not expensive to build, but if you do not need or want any of the mechs that are gestated using standard subcores, then it is safe to skip.

Note that every mech that requires a standard subcore is created at a [[large mech gestator]] and uses the [[large mech recharger]]. These two buildings cost {{Icon Small|steel||{{#expr: {{Q|Large mech gestator|Resource 1 Amount}} + {{Q|Large mech recharger|Resource 1 Amount}} }} }} [[steel]] and {{Icon Small|component||{{#expr: {{Q|Large mech gestator|Resource 2 Amount}} + {{Q|Large mech recharger|Resource 2 Amount}} }} }} [[component]]s. This is in addition to costs of the softscanner itself and the gestation of the mechs.

== See also ==
* [[Subcore encoder]] - Creates [[basic subcore]]s.
* [[Subcore ripscanner]] - Creates [[high subcore]]s.

== Version history ==
* [[Biotech DLC]] Release - Added.
* [[Version/1.4.3534|1.4.3534]] - Added more feedback to subcore scanners.
* [[Version/1.4.3541|1.4.3541]] - Fix: Softcore{{Sic}} scanner tooltip formating.
* [[Version/1.4.3555|1.4.3555]] - In the 'Completed scan' message sent when subcore scan is cancelled, changed 'cancel load' to 'cancel scan'.

{{Nav|biotech|wide}}
[[Category:Biotech (Buildings)]]

Pollution

2026-02-01T17:06:59Z

Aelanna: Rephrasing intro.

{{Biotech}}
{{Stub|reason=Mechanics (Pollution spread / acidic smog % chance / wastepack cocoons), detailed analysis}}
'''Pollution''' refers specifically to map pollution caused by the spread of ''toxic'' pollution, which generally results from the use of [[toxifier generator]]s or the decay of [[toxic wastepack]]s, which are generally produced via the recharging of [[allied mechanoid|friendly mechanoid]]s. Using [[wood-fired generator]]s or [[chemfuel generator]]s does not produce pollution.

== Creation and spread ==
==== Within colonies ====
[[File:pollution_spread.png|400px|thumb|right|Ground pollution generated by a toxifier generator, visualized by the pollution overlay. The tiles under the player-built walls are polluted, though this does not show on the overlay.]]
Each [[toxic wastepack]] that is destroyed or disintegrates creates 6 tiles of pollution. Any means of destroying wastepacks creates pollution, except for the [[wastepack atomizer]].

A [[toxifier generator]] creates 6 tiles of pollution every 3 days.

[[Defoliator ship]]s will pollute an expanding circle of tiles when landing, centered on the ship. This is in addition to the actual defoliation; the pollution is separate and spreads much slower.

Pollution created again in the same area will spread in an expanding circle. Natural rock walls block the pollution spread, but player-made walls and other structures do not (including smoothed walls).

Pawns lingering in polluted tiles will accumulate [[Toxic buildup]] at a rate of 40% per day, assuming no [[Toxic Environment Resistance]] or [[Toxic Resistance]]. Unlike [[Toxic fallout]] or other map conditions, this is not mitigated by roofing the tile.

==== On the World Map ====
Hexes on the world map can be polluted on world generation or by player action.

Initial pollution coverage can be configured on world generation, with 5% as a default. Pollution will be distributed in splotches around the world map, with heavily polluted hexes surrounded by less polluted hexes.

Dumping wastepacks on a hex utilizing [[caravan]]s or [[transport pod]]s will increase the pollution percentage of the hex by 0.05% per Wastepack dumped, or 1.3% per full transport pod. Once a world map hex reaches 100% pollution, any additional pollution gain will instead happen to one of its 6 possible neighboring tiles- this can spread pollution to the player's colony if one is not careful.

Caravans walking through polluted terrain will accumulate [[Toxic buildup]] based on their [[Toxic Environment Resistance]] and [[Toxic Resistance]] stats. The unmitigated rate will be at 20%/day for Moderately Polluted tiles (50-75% pollution) and 40% per day for Extremely Polluted tiles (75~100% pollution).

Dumping wastepacks within 15 tiles of another faction settlement will cause the player to take a relationship penalty, scaling up with the number of wastepacks dumped and proximity to the settlement('''relationship penalty'''='''Number of wastepacks''' * '''distance coefficient'''|The distance coefficient represents the impact of the distance from the waste pod drop location to the faction position on the relationship penalty. The coefficients are as follows: 100% for 0 tiles, 50% for 1 tile, 20% for 2-4 tiles, 10% for 5-7 tiles, and 6.67% for 8-16 tiles ). Outlander and pirate factions may send a [[drop pod]] of waste back at you, while hostile factions can [[raid]] you(Probability = '''relationship penalty'''%).

== Summary ==
{{Stub|section=1|reason = numbers and world tile and map tile effects, missing plants that can occur}}
Pollution takes the form of polluted tiles. Polluted soil has a fertility of 50%, as long as the soil's original fertility is greater than 0%. Polluted soil can only grow a limited number of plants, namely:
* [[Toxipotato plant]]s;
* [[Devilstrand]];
* [[Psychoid plant]]s; and
* [[Gray pine tree]]s

Having polluted tiles increases the map's overall pollution, which causes a number of effects.

Colonists will receive [[toxic buildup]] while standing or walking on these tiles at a rate of 40% severity per day.

Pollution on the ground can be turned back into toxic wastepacks with a [[pollution pump]], or by ordering colonists to clean it up.

=== Acidic smog ===
If there is enough pollution present within 4 tiles of your world tile, a weather effect known as Acidic smog will occur. How often depends on the level of pollution present. Tiles 2-4 spaces away have a 0.5x multiplier to pollution.

Acidic smog covers the outdoor area with a greenish haze, reduces light levels by {{--|28%}}, slows plant growth by {{Bad|x50%}} (stacking with reduced light for a total of {{bad|22%}} growth), gives non-immune colonists the {{--|5}} ''Acidic Smog'' [[mood]]let, and [[deteriorate]]s items at 300% speed. Items and pawns indoors are not affected by acidic smog in any way. Having the [[Total antitoxic lungs]], [[Tox immunity]] or [[Breathless]]{{OdysseyIcon}} genes, having any installed [[Detoxifier lung|Detoxifier]] or [[Fleshmass lung]]s or having 100% [[Toxic Environment Resistance]] / [[Toxic Resistance]] renders immunity to the acidic smog moodlet. [[Partial antitoxic lungs]] / [[Tox resistance]] genes do not resist the acidic smog moodlet.

Despite what players may expect, acidic smog itself does not have any negative health effects. The smog will affect pollution-friendly plants such as [[toxipotato plant|toxipotatoes]] the same as it does other plants. It does not provide or maintain [[Pollution stimulus (gene)|Pollution stimulus]]'s effects.

=== Insectoids ===
Originally engineered as anti-mechanoid bioweapons, Giant [[insectoid|insects]] are drawn to pollution. When a toxic wastepack is destroyed, there's a chance for insectoid cocoons to emerge from the ground. These cocoons will hatch if a pawn comes within a small radius of them.

=== Pollution stimulus ===
{{Main|Pollution stimulus}}
Insects and humans with the [[Pollution stimulus (gene)|Pollution stimulus]] gene are stimulated by the toxic fumes of polluted terrain, making them faster and deadlier.
* Pollution stimulus (minor):
** Moving x110%
** Consciousness +5%
* Pollution stimulus (moderate):
** Moving x115%
** Consciousness +5%
* Pollution stimulus (maximum):
** Moving x120%
** Consciousness +5%

== Pollution mitigation ==
{{For|dealing with [[wastepack]]s themselves|Toxic wastepack#Disposal}}

=== Cleaning polluted tiles ===
* Having colonists manually clean pollution via the Zoning tab. This exposes them to toxic buildup.
* [[Pollution pump]]s automatically pick up pollution in the area when [[power]]ed.
* Letting [[polux tree]]s cleanly consume pollution. However, they only grow in sufficiently polluted areas, and seeds are difficult to come across.
Note that the former two ways of cleaning pollution up only turn it into [[toxic wastepack]]s, which then need to be [[Toxic_wastepack#Disposal|dealt with]] somehow.

=== Living with pollution ===
* '''[[Apparel]] items'''. [[Face mask]]s ({{+|50}}%), [[gas mask]]s ({{+|80}}%) and the [[Prestige robe]] ({{+|20}}%) give [[Toxic Environment Resistance]]. This protects the user from accumulating [[toxic buildup]] as quickly.
* '''[[Artificial body parts|Artificial parts]]'''. The [[detoxifier kidney]] ({{+|50}}% [[toxic resistance]]) and [[detoxifier lung]] ({{+|60}}% environmental resistance) will slow the effects of pollution. Two organs of the same type will stop toxic effects of pollution.
* '''[[Gene]]s'''. Tox resistance gives {{+|50}}% toxic resistance. Partial antitoxic lungs give {{+|50}}% environmental resistance. Tox immunity or Total antitoxic lungs render full immunity to pollution and acidic smog.

Toxic resistance stacks additively with other sources of ''Toxic Resistance'', but stacks multiplicatively with Toxic ''Environment'' resistance. For example, a face mask and detoxifier lung, or face mask and partial antitoxic lungs, offers 100% resistance to pollution. A face mask and detoxifier kidney only provides 75% resistance to pollution.

== Version history ==
* [[Biotech DLC]] Release - Introduced.
* [[Version/1.4.3682|1.4.3682]] - Fix: Pollution overlay grid not updating after cell-filling buildings are destroyed.
* [[Version/1.5.4062|1.5.4062]] - Fix: Several issues with pollution clearing.
* [[Version/1.6.4566|1.6.4566]] - Gravships no longer clear pollution when landing.

{{Biotech navbox}}

[[Category:Game mechanics]]

Metalhorror

2026-02-01T17:03:10Z

Aelanna: Removing check tag, adding kibble to list of non-infectable foods.

{{Anomaly}}
{{Spoiler}}
{{Rewrite|reason=General - Page needs overhaul, needs cleanup and redistribution of info into correct sections. Also missing important content e.g. detection mechanics}}
{{Infobox main|entity
| name = Metalhorror
| image = Metalhorror.png
| description = A horrific shifting mass of metal filaments, blades, and instruments. This metal is maintained and regenerated by a circulating dark fluid.<br/>While dormant, fluid metalhorrors are hidden in a host body. They use their host to infect others, creating more metalhorrors. If detected or endangered, the metalhorror will form a jagged exoskeleton and cut its way out of the host's flesh.<br/>An emerged metalhorror will eventually enter a low-energy hibernating state if left undisturbed.

| type = Entity
| type2 = Advanced
| flammability = 2

| minimum containment strength = 110
| anomaly knowledge = 4
| knowledge category = Advanced
| study interval = 120000
| bioferrite density = 4
| requires holding platform = true
| min monolith level for study = 1
| base escape interval MTB days = 60

| armorsharp = 50
| armorblunt = 50
| armorheat = 0

| combatPower = 300
| movespeed = 5.5
| healthscale = 0.6
| bodysize = 1
| diet = none
| lifespan = 250
| trainable = None
| juvenileage = 0.016667
| maturityage = 0.05
| psychic sensitivity = 1.5
| toxic resistance = 1
| vacuum resistance = 1
| min comfortable temperature = -100
| max comfortable temperature = 250

| gestation = 10
| meatyield = 0
| destroyyield = {{Icon Small|Bioferrite}} 10 - 20 + {{Icon Small|Shard}} 0 - 1

| attack1dmg = 20
| attack1type = Cut
| attack1cool = 2
| attack1part = left blade
| attack2dmg = 20
| attack2type = Stab
| attack2cool = 2
| attack2part = left blade
| attack3dmg = 20
| attack3type = Cut
| attack3cool = 2
| attack3part = right blade
| attack4dmg = 20
| attack4type = Stab
| attack4cool = 2
| attack4part = right blade
| attack5dmg = 9
| attack5type = Blunt
| attack5cool = 2
| attack5part = head
| attack5chancefactor = 0.2

| defName = Metalhorror
| label = metalhorror
}}

The '''Metalhorror''' is an [[entity]] that can threaten your colony. It will infect your colonists one by one and burst out of them when it is ready to attack.

== Occurrence ==
A metalhorror infection generally begins as a hidden illness suffered by a single pawn, which is initiated by a storyteller event that targets a pawn with a valid infection pathway. [[Creepjoiner]]s often come with drawbacks - one of which can be a metalhorror infection. Pre-infected pawns may arrive as [[guest]]s or [[raiders]].

During the [[monolith]] awakening, several mature metalhorrors will be spawned to defend each [[void structure]]. Additionally, once all void structures are defeated, a final group of metalhorrors will spawn around the [[void monolith]].

=== Infection ===
{{Stub|section =1 |reason=Comprehensive list of transmission vectors. Attacks by entities, operations of all kinds by an infected doctor, tending by infected, food cooked by infected, food fed by infected doctor, and sleeping in the same bed with infected all reported. These, others, and existing vectors need verification and specifics. detection process - gray flesh, does the number to detect scale with researcher stats, what is the cooldown between gray flesh drops, more specific values for randomness on interrogation and undetected emerges, etc. Social interactions have a small chance to detect a MH infection - questions to be answered: Chance? Reports of 0.1% but verify. Which interactions can trigger? Is it always honest (no false +ves, do two infected force a false -ve)?, Reports of animal interactions triggering it?

do interrogator stats affect detection rate, do they affect safe detections vs release triggering detections?

A non-colony, infected pawn of the map (e.g. released prisoner), triggers metalhorror release. transport pods excluded. your own colonists excluded.}}

Metalhorrors are entities that infect humans through their hosts, creating more of themselves as they do. It is possible to test or interrogate pawns in order to find out who is hosting a metalhorror. Upon detection through surgical inspection, and a random chance from being detected by interrogation (an option in the prisoner tab) or going undetected for too long, all metalhorrors will emerge out of their hosts and inflicting [[Damage_Types#Cut|cuts]]. The death of any host will also cause them to emerge, even if they have not been detected first. When emerging, metalhorrors will deal enough damage to down most hosts:
* They will never leave scars or kill their host when emerging.
* Ghouls and painless pawns can still be downed through damage to their legs. If they are not downed, they will have received enough damage to nearly kill them.
* Unconscious and incapacitated pawns will still receive damage albeit to a lesser extent.

Metalhorrors can spread between colonists in various ways.

The initial infection is activated by a miscellaneous storyteller event that chooses a random pawn under the player's control on the map (colonists, slaves, and prisoners) with a valid infection pathway:
* Implantation before arrival. This applies to any pawn upon first spawning, except for the initial colonists, babies, and duplicates from the [[corrupted obelisk]]. Additionally, use of a [[resurrector mech serum]] or a charge of [[death refusal]] will apply the pre-arrival infection pathway again, except to the aforementioned pawns. This will be listed as "implanter insectoid" for creepjoiners despite insectoids not being a valid infection pathway.
* During [[revenant]] hypnosis.
* The melee attack of a [[shambler]], [[fleshbeast]], [[noctol]], or [[sightstealer]].

Metalhorror implantation events do not cause any letter to appear, however gray flesh appearing does.

Note that an infection pathway is not by any means guaranteed to become a full-fledged metalhorror infection. Pawns with infection pathways are not considered metalhorror hosts and will not spread the infection or generate gray flesh until and unless the metalhorror event triggers on them. An infection pathway expires after 30 days, and a pawn can have up to 100 infection pathways at a time before old ones are deleted to make room for new ones. Metalhorror emergence does not remove infection pathways. If a metalhorror event triggers when no suitable target pawn possesses a valid infection pathway, the game will spawn a creepjoiner with a hidden metalhorror infection. It's highly recommended for players to quarantine new creepjoiners until they have been cleared for hidden infections. This is especially true if the creepjoiner spawned immediately after conducting a void provocation ritual.

Once a metalhorror infection is active, its host can secretly spread it to other pawns. Pawns infected this way gain the metalhorror infection immediately, rather than using the infection pathway system, and as such can start infecting other pawns from the moment they're infected. The following activities, when performed by an infectee, can spread a metalhorror infection:

{| class="wikitable sortable"
|-
! Infection event !! Details !! Infection chance per event
|-
! Sharing a bed
|
* An infected pawn sharing any two-person bed or sleeping spot spreads the infection to any bedmates.
* The pawns do not need to be in a relationship or participate in [[lovin]]' for the implantation to occur.
* Pawns sharing the same barracks but not the same two-person beds or sleeping spots will '''not''' spread the infection.
| 100%
|-
! Performing surgery
|
* Any medical bill performed on a pawn by an infected pawn can spread the infection.
** This includes minor operations that might not be obvious as vectors, such as anesthetization, administration of drugs, [[xenogerm]] implantation,{{BiotechIcon}} and [[Hemogen pack|blood transfusions]].{{BiotechIcon}}
* Tending '''does not''' spread metalhorror infections.
| 50%
|-
! Cooking a meal
|
* Each meal cooked by an infected pawn has a chance to infect a pawn that eats it.
** This chance is rolled upon consumption, not upon creation of the meal.
** Unlike food poisoning, there is no averaging of infection rates when a tainted meal is added to a meal stack - the number of tainted meals in the stack is kept constant, and pawns will prioritize consuming tainted meals.
** Pemmican, baby food, and kibble cannot be infected.
* '''After the infection is revealed, it is possible to have your colony reinfected by tainted meals.'''Even after the event has ended, the meals will retain their Metal Horror infectious properties and will not be neutralized. Unless you can guarantee that the cooks are not infected, you will need to discard all of the meals.{{Check Tag|Detail needed|Do you need to do the flesh research again or is it considered the same?}}
| 4%
|-
! [[Unnatural healing]]
|
* Use of the ability by an infected pawn on an uninfected pawn spreads the infection.
| 100%
|-
! Feeding patients
|
* An infected pawn feeding anything to a patient can infect the patient. This includes [[hemogen pack]]s{{BiotechIcon}} being fed to [[Hemogen|hemogenic]]{{BiotechIcon}} prisoners and patients.
| 30%
|}

=== Detailed Information to be cleaned up ===
{{Rewrite|section=1|reason=Move this info into the correct sections of this page}}
There are two separate metalhorror incidents. Both fire as Minor Threats.

Metalhorror implantation fires on a random colonist that meets specific criteria such as recently joined colony or damaged by [[entities]].
* Requires monolith level 1.
* Can trigger on day 30 at the earliest.
* 45 day cooldown
* Requires a colonist count of 4 and 300 [[raid points]].

Creepjoiner infected with Metalhorrors:
* Requires monolith level 2.
* Can trigger on day 10 at the earliest.
* 60 day cooldown.
* No raid point nor a Colonist count requirement.

The first gray flesh appears 1.5 to 2.5 days after infection. When a gray flesh is to be dropped, there is an additional 1 to 12 hour delay. One gray flesh can drop every 3 to 10 days.

If half of your colonists are infected, the chance for metalhorrors to emerge will approach 100% after a few hours.

== Summary ==
Contrary to other non-human entities, they have three different life stages. They need 1 day to grow from larva to juvenile, and another two days to grow from a juvenile to a mature metalhorror.{{Check Tag|Counts time inside?|When does this growth start? From exiting the pawn or from infection?}}

Metalhorrors do not leave behind [[corpse]]s when killed, instead breaking down into a pile of {{Icon Small|Bioferrite||10-20}} [[bioferrite]], and occasionally {{Icon Small|shard||1}} [[shard]].{{Check Tag|Chance?}}

=== Containment ===
The metalhorror yields 2.0 to 4.4 [[bioferrite]] and 160W to 220W per day.

=== Combat ===
When attacked, metalhorrors only receive 25% of damage.{{Check Tag|Stat?|Incoming Damage Multiplier?}} They can be stunned by EMP, but never adapt to it. They also have 200% [[flammability]].

A metalhorror's attacks are identical to those of a [[scyther]]. Metalhorrors attack with a blade attached to each arm, dealing a massive 20 damage per blade. While they technically have a blunt Head attack, they will never use it unless their arms are destroyed. Even for brawlers with high melee skill, metalhorrors are extremely dangerous.{{Check Tag|Maturity?|How do larval and juvenile metalhorrors compare to mature ones?}} Larval and juvenile metalhorrors deal less damage.

Metalhorrors' legs have a total of 36% chance to be targeted by damage, almost twice that of human legs, while having only 60% as much health. This makes them more likely to have both legs destroyed in combat.

Metalhorrors have a [[psychic sensitivity]] of 150%, making certain [[psycast]]s{{RoyaltyIcon}} more effective on them.

== Analysis ==
Metalhorrors are easy to fight if you have EMP weapons. Because they don't adapt to EMP, they can be stunned indefinitely

=== Metalhorror infection ===
Once gray flesh is discovered, it is important to consider the pawns most likely to spread infections - Cooks, Doctors, and Wardens.
* Tracing infections from an infected cook is nigh-impossible. Consider switching the entire colony to eating [[Nutrient paste meal|nutrient paste]] which will prevent meals from being an infection vector until the metalhorrors have been rooted out.
* Doctors only spread infections while operating or feeding patients, which allows some estimation as to who an infection might have been passed to. Do not schedule surgeries while a metalhorror infection is confirmed unless absolutely necessary. Pawns that have been downed and fed by doctors are susceptible to infection.
* Permanently downed prisoners (e.g those with legs removed), and recently acquired prisoners recovering from being downed in combat, are highly likely to be infected by an infected warden. Thankfully prisoners can be interrogated and their infections uncovered- even by infected wardens.
* Once a pawn has been confirmed as having an infection, if they share a bed or sleeping spot with another pawn, that other pawn will be infected.

==== Detection ====
After discovering gray flesh, colonists can occasionally notice "some combination of unusual behavior" in another colonist while chatting. The name of the infected colonist (as well as the suspicious one) will be revealed in a letter. This can give the player some hints about who is infected, and how the infection may be spreading throughout the colony. However, confirming metalhorror infection still requires a surgical inspection after gray flesh has been sufficiently studied.

[[Paramedic]]s{{BiotechIcon}} can never become infected or lie about test results, so they can be used to test for Metalhorror infections safely.

If you don't have a paramedic, the following procedure can be done after studying 2 pieces of gray flesh:

# Have 2 doctors
# The instant you become aware of a Metalhorror infection, have doctor 1 check someone other than doctor 2
# If they find an infection, doctor 1 is clear.
# If they do not, have doctor 2 check the patient
# if they find an infection, doctor 1 is infected
# If they do not, have doctor 1 check again
# if doctor 1 finds an infection, doctor 2 is infected
# if doctor 1 does not, then either both doctors are clear or both are infected.

Alternately, the player can systematically order every colonist to repeatedly conduct surgical inspections on a sacrificial pawn such as a prisoner. Eventually, the sacrificial pawn will be infected with a metalhorror which will be detected with a subsequent examination.

In the event of total infection, a sufficient number of [[Mechanoids]] can safely clear out the revealed Metalhorrors, as long as the [[Mechanitor]]s {{BiotechIcon}} they are linked to are still alive.

==== Force emergence by bed sharing ====
Since metalhorrors always emerge when they have infected half of your colony, and infection occurs as soon as two pawns share the same bed, you can trigger metalhorror emergence by letting your pawns share beds.

Some pawns must stay outside to fight the metalhorrors though. Since they may also be infected, each of them should stay in a different room to contain the potential metalhorror. These pawns should have good melee and doctor skills to tend your downed pawns afterward.

The number of participating pawns should be at least half of your colony to guarantee that the threshold is reached. Create a double sleeping spot in a separate room for every 2 participating pawns. Then create anethetize bills for each pawns and assign them to rest on the same spot (the game will say that the spot has been reserved, but just prioritize it anyway). You should assign pawns to sleep with someone who is not their lover or spouse, since lovers should already have infected eachother when they share the same bed before. If the threshold has been reached, metalhorrors should emerge after a few seconds. If not, swap the partners around until they emerge.

You can prepare for the emergence by armoring the pawns who have to stay outside and setting spiketraps in the bedrooms for the metalhorrors to trigger.

==== Prevention ====
Now as for preventing Metalhorrors from spreading premptively for the event of a infection, you can do the following
* Set a zone forbidding pawns from accessing prisons, kitchens and hospitals, and set that zone onto any pawn who has less then 30 days in their record, especially creepjoiners, or pawns who were attacked by revenants or any of the entities described in the summary, and keep note of the days in their record and set the zone off once the pathway has expired.
** Cooks can still butcher and cook pemmican safely and doctors can be left to treat animals if you separate those into different rooms.
** Slaves do not have a record for time spent as a colonist so stats like time spent under a roof can be used as a rough estimate.
** Colonists that were in the colony for over a year have their record set as #.# making keep track of them more difficult, the combat log can be used instead albeit those are prone to being wiped. {{Check Tag|When?|When do combat logs expire, if its less then 30 days then this might not be as effective}}
* If a gray flesh event sets off then you can check any pawns who were assigned that zone.
* For lovers you can place another bed in their room and assign the suspect to it, preventing the sleeping alone moodlet. a bedroll may be used instead to prevent the room's space stat from being reduced.
* For combat encounters with entities you should ideally avoid having humans do melee combat, and let mechanoids and animals tank the hits instead.

Imprisoning suspects such as creepjoiners runs the risk of [[prison break]]s and thus the possibility of outright losing them due to casualities or escaping so assigning a "Quarantine" zone to them until their drawback is identified can be a better alternative.

=== Mature metalhorror ===
You will fight groups of mature metalhorrors during the [[monolith]] awakening, they can do serious damage to your colony, but do not cause metalhorror infection.

Fighting metalhorrors is much like fighting [[scyther]]s, due to their identical melee attacks and fighter role in combat. The same tactics that apply to scythers largely also apply to them, as they also vulnerable to EMP and can similarly be lured into [[spike trap]]s. However, Metalhorrors are much faster and more resistant to damage than scythers.

One disadvantage they have compared to scythers is that Metalhorrors are highly flammable. They can be ignited very easily and will disengage from combat while on fire. A pawn armed with an [[incendiary launcher]], [[molotov cocktails]], or [[incinerator]] can easily cripple a pack of metalhorrors.

=== Containment ===
Due to the high containment requirements of metalhorrors and their sharp attacks, healthy ones are dangerous to maintain. However, legless metalhorrors can be captured with no risk of escape. They yield a decent 2.0 - 4.4 bioferrite/day{{Check Tag|Verify|How is this number derived and then verify the range}} depending on body size. If you find downed metalhorrors with damaged legs, continue to punch them with bare hands until both their legs are shattered, or death. Metalhorrors' high armor makes the first case more likely to happen than other entities.

== Health ==
=== Body parts ===
{{Recode|section=1|reason="Metalhorror" body type not supported.}}
{{Animal Health Table|Metalhorror}}
=== Armor ===
{| class="wikitable"
! Armor
|-
| {{Apparel Protection Chart
| set1name= {{P|Name}} (Sharp) | set1armor1={{P|Armor - Sharp}}
| set2name= {{P|Name}} (Blunt) | set2armor1={{P|Armor - Blunt}}
| set3name= {{P|Name}} (Heat) | set3armor1={{P|Armor - Heat}}
| color= grey, blue, red
}}
|}
{{Pawn Attack Table}}

== Gallery ==
=== Larva ===
<gallery>
Metalhorror Larva east.png|East
Metalhorror Larva north.png|North
Metalhorror Larva south.png|South
</gallery>

=== Juvenile ===
<gallery>
Metalhorror Juvenile east.png|East
Metalhorror Juvenile north.png|North
Metalhorror Juvenile south.png|South
</gallery>

=== Mature ===
<gallery>
Metalhorror Mature east.png|East
Metalhorror Mature north.png|North
Metalhorror Mature south.png|South
</gallery>

===Infection Vectors===
<gallery>
Metal_Horror_Cooking.PNG|Cooking
Metal_Horror_Fingerspike_Attack.PNG|Fingerspike Attack
Metal_Horror_Meal_and_Surgery1.PNG|Feeding Meals and Surgery
</gallery>

== Version history ==
* [[Anomaly DLC]] Release - Added.
* [[Version/1.6.4518|1.6.4518]] - Fix: Added eyes to metalhorrors. Previously a metalhorror's mind core functioned as both its eyes and brain, allowing the "[[Hediffs#Dirt|kick dirt in eyes]]" melee effect when fighting on appropriate terrain to instantly incapacitate them until the effect wore off.
* [[Version/1.6.4566|1.6.4566]] - Fix: Metalhorror filth not spawning if previous map was abandoned with specific timing.

{{Nav|entity|wide}}
[[Category: Entities]]

Rooms

2026-02-01T16:54:02Z

Aelanna: Rephrasing edited outdoor temperature explanation.

<span style="display:none;"><ref name="penalty">Work speed penalty of 80% if not placed in the room with the correct role.</ref></span>

{| align=center | {{Gameplay Nav}} |}

----

{{TOCright}}

A '''room''' is a space fully enclosed by impassable objects such as [[wall]]s, [[door]]s (open or closed), [[vent]]s, natural rock, or [[cooler]]s. Corners do not need to be filled in order to enclose a room.

== General ==
A room that's at least 75% [[roof]]ed is considered [[indoors]]. This distinction affects [[temperature]], [[Deterioration Rate]], [[Work Speed Factor]], and pawns' [[outdoors]] and indoors needs. {{Check Tag|Verify|Does it really affect all these stats, and how specifically?}}

An indoor room will remain an indoor room when its doors are open — even when they're held open permanently. [[Vac barrier]]s also enclose a room despite not being impassable. If a door is destroyed and the room is no longer enclosed, the room will instantly be considered outdoors.

The maximum size of a room is 36 [[#Map regions|map regions]]. The equivalent size in tiles varies based on the position and shape of the room, but as reference:
* The maximum area possible per room is 5,184 tiles (72x72).
* An empty 50x50 square room is the largest room that won't have issues with map regions.
* The more complex the shape of a room, the more likely it is to run into problems with map regions.
* Above this size, the area in question will be treated as a non-room indoors space.

=== Temperature ===
Indoor rooms can have a different temperature than the outside. Open [[door]]s, open [[vent]]s, or missing roof tiles will increase the rate at which heat is exchanged with the outdoors. For further information, see the [[temperature]] page.

If 25% or more of a room is unroofed, if it is open to the map edge, or is otherwise not fully enclosed (missing a wall), then it is considered outdoors and it will instantly equalize with the outdoor temperature.

== Roles ==
'''Room roles''' are assigned to a room based on the buildings they contain, such as a ''kitchen'' when containing an [[electric stove]] or a [[fueled stove]]. They determine whether a colonist is affected by all, some, or none of the room stats.

=== Summary ===
Certain room roles grant [[mood]]lets based on their [[Impressiveness]], which is affected by all four substats. To gain the moodlet, the room must be used by a pawn for the role's associated purpose (i.e., eating at a table for the dining room role or playing billiards for the rec room role). Despite the game displaying only one role, rooms can grant moodlets from multiple roles when used for that role. The moodlets are typically {{Check Tag|When not?}} applied when a colonist ''begins'' said activity in the room, and they last for 24 hours. {{Check Tag |Verify| What about deathresting? It uses a separate thought.}}

Buildings associated with hospitals, laboratories, and kitchens make direct use of the [[Cleanliness]] stat for their [[Work Speed Factor]].

Some room roles cannot have certain buildings inside without inflicting a mood penalty (i.e., [[Titles#Thrones and Bedrooms|throne rooms]] {{RoyaltyIcon}} and temples {{IdeologyIcon}} with [[Production|workstations]]).

Pawns also have separate needs for [[Beauty]] and [[Space]], which every room can fulfill. Unlike the room stats of the same name, these needs are checked within a certain radius from the pawn, as opposed to anywhere in the room. See those pages for further details.

=== Score calculation ===
For each room, every room role is given a score based on the buildings inside, and the role with the highest score is the one displayed. In the case of a tie, the earlier roles on the following table take priority.

For the purposes of room role scoring, the following are considered non-baby human beds: {{RoomRolesBuildingList|Bed-associated rooms}}.

=== List of roles ===
{| class="wikitable"
! Label
! Mood impact
! Related stats
! Score calculation logic
|-
| Room
| None
| None ||
* Returns a score of 0.99.
|-
| Bedroom <ref name="owner name">This role will have its owners' name added to its name.</ref>
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There are no human beds.
** There is at least 1 medical human bed or at least 1 prisoner human bed.
** There is more than 1 non-assigned human bed.
** There is at least 1 adult assigned and there are other pawns assigned that are not in its love cluster.<ref>A pawn's love cluster is all the other pawns that can be linked to the pawn through a chain of romantic relationships.</ref>
** There is at least 1 child assigned and there aren't any adults assigned that are a parent of the child.
* Returns 100,000 score otherwise.
|-
| Prison cell <ref name="owner name" />
| [[Mood#Situational RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There is more than 1 humanlike bed.
* Returns 170,000 score for a non-medical prisoner humanlike bed.
* Returns 100,000 score for a medical prisoner humanlike bed.
|-
| Dining room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 12 score per each one of the following: {{RoomRolesBuildingList|Dining room}}.
|-
| Rec room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 7 score per each one of the following: {{RoomRolesBuildingList|Rec room}}.
|-
| Hospital
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]], [[Room stats|Cleanliness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** There are no medical humanlike beds.
* Returns 100,000 score otherwise.
|-
| Laboratory
| No
| [[Room stats|Cleanliness]]
|
* Returns 60 score per each one of the following: {{RoomRolesBuildingList|Laboratory}}.
|-
| Workshop
| No
| None
|
* Returns 27 score per each one of the following: {{RoomRolesBuildingList|Workshop}}. The [[crafting spot]] does ''not'' count.
|-
| Storeroom
| No
| None
|
* Returns 1 score per each one of the following: {{RoomRolesBuildingList|Storeroom}}.
|-
| Barracks <ref name="owner name" />
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** The room is a valid bedroom.
* Returns 100,100 score for every non-medical humanlike bed otherwise.
|-
| Prison barracks <ref name="owner name" />
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There are less than 2 prisoner beds.
* Returns 100,100 score per non-medical prisoner bed and 50,001 per medical prisoner bed.
|-
| Kitchen
| No
| [[Room stats|Cleanliness]]
|
* Returns 28 score per production building that has at least 1 recipe that produces an edible result. The following fulfill the requirement: {{RoomRolesBuildingList|Kitchen}}. The [[brewery]], [[butcher spot]], and [[butcher table]] do ''not'' fulfill the requirement.
|-
| Tomb
| No
| None
|
* Returns 50 score per each one of the following: {{RoomRolesBuildingList|Tomb}}.
|-
| Barn
| No
| None
|
* Returns 7.6 score per non-humanlike bed, which are the following: {{RoomRolesBuildingList|Barn}}.
|-
| [[Throne room]] {{RoyaltyIcon}}
| No
| [[Impressiveness]]
|
* Returns 10,000 score if there is any one of the following: {{RoomRolesBuildingList|Throne room}}.
* Returns 0 score otherwise.
|-
| Temple {{IdeologyIcon}} <ref>This role changes to the ideoligion's set temple name.</ref>
| No
| None
|
* Returns -1 score if the [[Ideology DLC]] is not active.
* Returns 0 score if there are no altars with the colony's ideology.
* Returns 75 score per altar with the colony's ideology, with a minimum of 2,000 score. The following are considered altars: {{RoomRolesBuildingList|Temple}}.
|-
| Nursery {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 non-medical prisoner bed or at least 1 non-baby bed.
** There are less than 2 baby beds.
* Returns 100,200 score per baby bed. The following are considered baby beds: {{RoomRolesBuildingList|Nursery}}.
|-
| Playroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 humanlike bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Playroom}}.
|-
| Classroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 human bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Classroom}}.
|-
| Deathrest chamber {{BiotechIcon}}
| Yes
| [[Room stats|Impressiveness]]
|
* Returns 100 score per [[deathrest casket]] {{BiotechIcon}} and 50 score per [[deathrest accelerator]] {{BiotechIcon}}, [[glucosoid pump]] {{BiotechIcon}}, [[hemogen amplifier]] {{BiotechIcon}}, [[hemopump]] {{BiotechIcon}}, or [[psychofluid pump]] {{BiotechIcon}}.
|-
| Containment cell {{AnomalyIcon}}
| None
| None
|
* Returns 100 score per [[holding platform]] {{AnomalyIcon}} or [[holding spot]] {{AnomalyIcon}} and 50 score per [[bioferrite harvester]] {{AnomalyIcon}}, [[electric inhibitor]] {{AnomalyIcon}}, or [[electroharvester]] {{AnomalyIcon}}.
|-
| Ceremonial chamber {{AnomalyIcon}}
| None
| None
|
* Returns 200 score per each one of the following: {{RoomRolesBuildingList|Ceremonial chamber}}.
|-
|}

Other pieces of [[furniture]] not mentioned, such as [[chair|chairs]], are not considered for score calculation.

== Stats ==
[[File:quality preview.png|300px|right]]
'''Room stats''' are values of a room that passively affect both [[thought]]s about the room itself and some events and activities that take place within. These include [[Impressiveness]], which is calculated from four composite stats: [[Wealth]], [[Beauty]], [[Space]], and [[Cleanliness]]. These base stats are automatically calculated from [[buildings]], [[floor]]ing, [[filth]], the room's perimeter, and items within the room.

Room stats can be inspected with the room stats display, which can be toggled with a button in the lower right corner of the screen or a hotkey (''G'' by default). Additional information can also be viewed by holding down the ''Alt'' key.

Room stats affect the following:
* Medical treatment quality (Cleanliness)
* Research speed (Cleanliness)
* [[Food poisoning]] chance in prepared meals (Cleanliness)
* [[Mood#Room_stats|Mood]] of the people using them (Impressiveness)

The following traits are affected by room stats:
* [[Greedy]] - Decrease without sufficiently Impressive bedroom.
* [[Jealous]] - Decrease if anyone has a noticeably better bedroom. {{Check Tag|How much?}}
* [[Ascetic]] - Decrease if room is too Impressive. Increase if bedroom is dull or worse.

=== Impressiveness ===
The value for '''Impressiveness''' is based on the four other room stats ('''Wealth''', '''Beauty''', '''Space''', and '''Cleanliness''').

The mood effects from the room depend on the Impressiveness level, and not on the precise value. That value is rounded ''down'' to the nearest whole number, and a label (or "level") of Impressiveness will be given to the room, according to the table below. This level is used to apply the relevant thought, positive or negative.

The exact mood effects depend on the [[Room#Roles|room role]], with different rooms having different values at each level. For more information, see [[Mood#Room stats|this section of the Mood page]]{{Check Tag|Outdated link}} For bedrooms, dining rooms, and rec rooms, the effects are as follows:{{Check Tag|Verify table|Add values for other room types}}

::{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! Mood impact
|-
| < 20
| awful
| {{Bad|-2}} (bedrooms only)
|-
| >= 20 and < 30
| dull
| ''none''
|-
| >= 30 and < 40
| mediocre
| ''none''
|-
| >= 40 and < 50
| decent
| {{Good|+2}}
|-
| >= 50 and < 65
| slightly impressive
| {{Good|+3}}
|-
| >= 65 and < 85
| somewhat impressive
| {{Good|+4}}
|-
| >= 85 and < 120
| very impressive
| {{Good|+5}}
|-
| >= 120 and < 170
| extremely impressive
| {{Good|+6}}
|-
| >= 170 and < 240
| unbelievably impressive
| {{Good|+7}}
|-
| >= 240
| wondrously impressive
| {{Good|+8}}
|}

==== Guidelines ====

Since the impressiveness calculation (explained below) is fairly involved, it is not practical to predict impressiveness levels in an actual game. However, the following rules of thumb can be applied:

* '''Keep all four room stats equally in mind.''' There is a heavy weighting towards whichever stat is weakest, which is counted as much as all three other stats combined. For example, having a masterpiece work of art in a large room (high ''wealth'', ''space'' and ''beauty'') is not very effective if the floor is covered in vomit and animal filth (low ''cleanliness''). It is quite difficult to compensate for one low stat by raising the other three.

* '''Making a particularly small room ''impressive'' is difficult.''' Room size is a limiting factor for Impressiveness. If you want to make the room "very impressive", it should have a space of at least around 25 (which still counts as "rather tight" in the game). E.g. a furnished bedroom with a 5x5 or 4×6 footprint would be fine, and a little smaller could still work, but it would be a challenge to get there with a 4x4 room. Note that any naturally "large" rooms like hallways, lobbies, recreation halls etc. will never run into this limitation at all.

* '''Cleanliness matters'''. Since the level of impressiveness is what counts, and there are sharp thresholds separating the levels, even a minute change of any of the values can have a strong effect. This is usually due to ''cleanliness'' changing (because the other factors are pretty much fixed); even a single speck of dirt on the floor can result in major [[mood]] changes. Make sure that the room is not too close to a level threshold, and keep it clean.

* '''Do not go overboard'''. There are sharply diminishing returns from increasing any room stat. Increasing any of the stats has dramatically diminishing returns with regards to impressiveness. It is not worth putting a lot of resources into any of the stats beyond a point.*
:: (* Not unless you care about the stat for other reasons; "room impressiveness" is not the only stat that can affect [[mood]]. Beauty, among others, has its own value.)

==== Formula ====
The actual formula for calculating impressiveness involves multiple steps, starting with the four room statistics (wealth, beauty, space and cleanliness) and resulting in a single integer value ''impressiveness''.

The calculation is done in several steps:
# Convert each stat into natural units, so that typical in-game stats end up in a range of comparable single digit values.
# Curve values beyond (-1, 1) using a natural logarithm.
# Average the four stats into an impressiveness score, weighted towards the lowest one
# Soft-cap the result according to the space of the room.

<div class="mw-customtoggle-EXImpressivness" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Detailed formula:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-EXImpressivness">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
===== Base values =====
Firstly, all four raw stats are scaled individually by applying a factor, deriving the ''base contribution'' for each stat:

: '''W'''<sub>b</sub> = ''wealth'' ÷ 1500
: '''B'''<sub>b</sub> = ''beauty'' ÷ 3
: '''S'''<sub>b</sub> = ''space'' ÷ 125
: '''C'''<sub>b</sub> = 1 + (''cleanliness'' ÷ 2.5)

===== Modified values =====
These base values are now modified if they lie outside the range (−1, 1), by applying the ''natural logarithm'' as follows: {{Check Tag|Add image|An image would be quite useful because the modified values are actually very visually intuitive despite the formula's complexity}}
m = 1 + ln(b) (if b >= 1)
m = [1 + ln(−b)] × −1 (if b <= −1)
(This is symmetrical for positive and negative values).

===== Impressiveness score =====
These modified values are then combined to give the ''impressiveness'' score as follows.

Take a weighted sum of the average of the values and the smallest of the values:
I = (65 × ('''W'''<sub>m</sub> + '''B'''<sub>m</sub> + '''S'''<sub>m</sub> + '''C'''<sub>m</sub>) ÷ 4) + (35 × min('''W'''<sub>m</sub>, '''B'''<sub>m</sub>, '''S'''<sub>m</sub>, '''C'''<sub>m</sub>))
This means that the smallest of the values contributes 51.25%, just over half, while the other three values each contribute 16.25%, or 48.75% combined.

As a final step we compare this impressiveness value to the ''spaciousness'' of the room:
S' = 500 × S<sub>m</sub>
If I > S', then
I' = 0.25 × I + 0.75 × S'
else
I' = I (no change)

This means a room's max impressiveness is soft-capped to 500% of their space score. However, this specific step is only relevant for very small, disproportionately luxurious rooms. Even a 60-space room (S = 0.5) will incur no penalty up to 240 impressiveness, enough to clear the highest bracket ("wondrously impressive"), and a 30-space room (S = 0.24) already reaches "extremely impressive" with no penalty.

===== Takeaways =====
It can be useful to think of impressiveness as a percentage value composed of four categories; a score of 1 in each category corresponds to 100 impressiveness, while values above 1 stop giving "fair" (ie. linear) returns. One unit of each stat is equivalent to each the following:
* ''Wealth'' of 1,500
* ''Beauty'' of 3
* ''Cleanliness'' of 0 (i.e. when using any cleanliness enhancers)
* ''Space'' of 125
Above these values, it begins to become more economical to invest attention in other stats. A "standard bedroom" of size 4×6, carpeted and containing bed, dresser, end table, lamp and plant pot will still have plenty of leeway in all categories (except cleanliness, which is at a natural 0 for a cleaned room); in this case, you will usually proceed by putting a sculpture or high quality armchair in the room, increasing beauty and wealth.

Furthermore, observe that the factors (i.e., modified values) for ''wealth'' and ''beauty'' will often be well above 1, but ''cleanliness'' and ''space'' usually lower than 1. Unless the room is "very spacious", or close to it, the decisive factor will thus be ''space'', then ''cleanliness''. In fact, even a well-cleaned room can never have a value over C = 1 (0 cleanliness; perfectly clean) or C = 1.215 (0.6 cleanliness; sterile), meaning rooms above ~100-120 impressiveness will ''always'' be bottlenecked by their cleanliness score. This makes "very impressive" (85-120 impressiveness) a natural set point for many rooms.

===== Example =====
Start with a room with a ''wealth'' of 3000, ''space'' of 25, ''cleanliness'' of 0, beauty of 3.
: '''W'''<sub>b</sub> = ''3000'' ÷ 1500 = 2, but this is curved to 1 + ln(2) = '''1.69'''
: '''B'''<sub>b</sub> = ''3'' ÷ 3 = 1
: '''S'''<sub>b</sub> = ''25'' ÷ 125 = 0.2
: '''C'''<sub>b</sub> = 1 + (''0'' ÷ 2.5) = 1

This makes the average score (1.69 + 1 + 0.2 + 1) ÷ 4) = 0.97 and the lowest score 0.2 (space).

From the above numbers, we can calculate the base Impressiveness
: I = (65 × 0.97) + (35 × 0.2)
: I = 63 + 7
: I = 70 (70.21 unrounded)
Now, I < 500 × '''S'''<sub>m</sub> (70 < 100), so there is no space penalty. Therefore, the reported Impressiveness of the room is 70 or "somewhat impressive"

If we were to increase the ''wealth'' of the above room by 6000 (4 units), our W<sub>m</sub> would become 6 -> 1 + ln(6) = 2.79 (+1.1 increase). Wealth wasn't the lowest stat, so this would only improve impressiveness by 1.1*16.25% = 17.9%, resulting in a score of 88 or "very impressive"

If we were to increase the original room's space by 10 units instead, '''S'''<sub>m</sub> becomes 0.28 (0.08 increase). Increasing the bottleneck stat results in a change of 0.08*51.25% = 4.1%, or 74 total impressiveness or "somewhat impressive"
</div></div>

=== Wealth ===
This is the sum of the [[Market Value]] of all items in the room and all walls and doors surrounding the room. Walls, doors, columns and animal flaps in the outer corner count as well. The value of [[power conduit]]s in walls ''is'' also included, however, for some reason building or deconstructing a conduit doesn't immediately update room wealth. Only if wealth is recalculated for some other reason, is the value of the conduits included. The same is true when building a column in the outer corner of the wall.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < 500
| impoverished
|-
| >= 500 and < 700
| somewhat poor
|-
| >= 700 and < 2000
| mediocre
|-
| >= 2000 and < 4000
| somewhat rich
|-
| >= 4000 and < 10000
| rich
|-
| >= 10000 and < 40000
| luxurious
|-
| >= 40000 and < 100000
| very luxurious
|-
| >= 100000 and < 1000000
| extremely luxurious
|-
| >= 1000000
| unbelievably luxurious
|}

=== Beauty ===
This is the average environmental beauty of the room including its walls and doors with a penalty for small rooms. Walls, doors and columns in the outer corner count as well. Building or deconstructing a column in the outer corner doesn't trigger a recalculation however. Floor tiles underneath walls and doors have no influence.

Room beauty is calculated as:

<pre>TotalBeauty = sum(beauty for each internal cell) + sum(beauty for each adjacent cell)
WeightedSize = size if (size > 40) else (20 + size / 2)
RoomBeauty = TotalBeauty / WeightedSize</pre>

This means that all rooms with less than 40 internal space will have their beauty penalised.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < -3.5
| hideous
|-
| >= -3.5 and < 0
| ugly
|-
| >= 0 and < 2.4
| neutral
|-
| >= 2.4 and < 5
| pretty
|-
| >= 5 and < 15
| beautiful
|-
| >= 15 and < 50
| very beautiful
|-
| >= 50 and < 100
| extremely beautiful
|-
| >= 100
| unbelievably beautiful

|}

=== Space ===
Indicates how much free space is available in the room. A room's Space score is 1.4 times the number of tiles in the room. Objects that prevent a pawn from standing in a space will decrease the available space in the room by 0.9 per tile the object covers. Thus, an occupied tile contributes a total of 0.5 to space. Objects that reduce space include beds, tables, workbenches, lamps, and heaters. Stools and chairs do not reduce space.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! typical size*
|-
| < 12.5
| cramped
| 3x4 or smaller*
|-
| >= 12.5 and < 29
| rather tight
| 3x6, 4x5*
|-
| >= 29 and < 55
| average-sized
| 4x7, 5x6*
|-
| >= 55 and < 70
| somewhat spacious
|-
| >= 70 and < 130
| quite spacious
|-
| >= 130 and < 349.5
| very spacious
|-
| >= 349.5
| extremely spacious
|}
: (* These are "safe" approximations; as described, the items placed <u>in</u> the room can greatly reduce the effective size. For example, an empty 5x5 room has space (25 x 1.4 =) 35, easily "average" - when empty. However, placing just one bed (2 tiles), one table (2 tiles), a light, a heater, a plant pot and one artwork (1 tile each, a chair is "free") in that room reduces the effective space by -7.2 (= 8 tiles x .9), and the effective space is now 27.8, "rather tight".)
: (* Due to floating point inaccuracies, sometimes a room that is right on a threshold may randomly count for one category or the other. For example, a room with 5 standable tiles and 11 walkable but non-standable tiles should come out to exactly 12.5 score, but may result in either "cramped" or "rather tight". It's safest to not rely on exact values.)

Note, that space of the room affects only its impressiveness. Careful to not confuse with Pawn's [[space]] need.

=== Cleanliness ===
This stat affects [[Surgery_Success_Chance_Factor#Room_Cleanliness_Multiplier|Surgery Success Chance]], [[Research#Research speed|research speed]], the chance that cooked meals will cause [[food poisoning]], and gene [[Assembly Speed Factor]].{{BiotechIcon}} A room's cleanliness is the average cleanliness score of all tiles in the room. It is determined by the type of [[floor]]ing, the presence of any [[filth]], and the cleanliness value of some furniture such as the [[butcher table]] and the [[stonecutter's table]]. Note that the type of [[floor]] under a door doesn't count for Cleanliness, but filth under a door does count.

<div style=display:inline-grid>
:::{| class="wikitable"
! Room Cleanliness
! Description
|-
| < -1.1
| very dirty
|-
| >= -1.1 and < -0.4
| dirty
|-
| >= -0.4 and < -0.05
| slightly dirty
|-
| >= -0.05 and < 0.4
| clean
|-
| >= 0.4
| sterile
|}
</div>
<div style=display:inline-grid>
:{| class="wikitable"
|-
! Surface
! Cleanliness<br/>Value
|-
|[[Void metal ]]{{AnomalyIcon}} || 1
|-
| [[Sterile tile]] floor || 0.6
|-
| [[Steel tile|Steel]], [[Silver tile|Silver]] or [[Gold tile|Gold]] floor || 0.2
|-
|[[Bioferrite plate]]{{AnomalyIcon}} || 0.2
|-
| all other constructed [[floor]]ing<nowiki>;</nowiki> [[Bridge]]s || 0
|-
| Natural stone ([[Rough stone|rough]] or [[Smooth stone|smoothed]]) || 0
|-
| [[Straw matting]] || -0.1
|-
| all other [[Environment#Terrain|natural surfaces]] (soil, gravel, etc.) || -1
|-
| [[Marsh]], [[Marshy soil]], [[Mud]], [[Broken asphalt]] || -2
|-
| [[Chunk]]s || -2
|-
|[[Flesh]]{{AnomalyIcon}} || -3
|-
| [[Filth|Dirt, rubble, all other filth]] || -5
|-
| [[Filth|Blood]] || -10
|-
| [[Filth|Insect blood, vomit, fuel puddle]] || -15
|-
| [[Filth|Corpsebile]] || -20
|}
</div>

Using "Toggle the beauty display" can help locate filth in a given room, which typically stands out due to its negative beauty.

== Map regions ==
Upon map generation, the map is divided into chunks of 12x12 squares called map regions. Each region requires a contiguous area and will be subdivided otherwise. Under no circumstance will a region extend beyond the initial 12x12 grid. Impassable buildings (both natural and artificial) are not considered as part of any map region for this purpose and will subdivide existing map regions accordingly. Regions will fuse when possible. Map regions are used for several calculations and can be seen in game via the debug option "Draw Regions".

<div class="mw-customtoggle-myDivision" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Some additional notes:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
* Impassable buildings are never part of any map region.
** Impassable non-walls (ex: [[Ship engine]]) may create a "red" temporal map region on construction that will be removed once anything else is build/destroyed.
* Impassable terrain creates map regions confined to its extension.
** These regions don't interact with the regular ones, but otherwise follow the stated rules.
* Passable buildings, such as [[fence]]s and [[barricade]]s, create map regions along their extension.
** These "fence" regions won't interact with other kinds, but otherwise follow the stated rules.
* Doors have unique behavior
** Single tile doors create a 3 tile map region centered on the doors' tile, following the door's orientation, that overlaps with other map regions.
*** Impassable objects will delete the overlapping section, no interaction otherwise.
** Double tile doors create 2 map regions, 1 for each of its tiles.
** The map regions created by doors don't interact with any other, not even each other.
* The grid defining regions is drawn from the bottom-left of the map row by row.
</div></div>

== Version history ==
* [[Version/0.12.906|0.12.906]] - Added.
* 1.1 - Added room stats gizmo, which displays the stats of the room containing a selected building, at a glance.
* [[Royalty DLC]] release - Throne room role added.
* [[Ideology DLC]] release - Temple room role added.
* [[Version/1.3.3072|1.3.3072]] - Fix: Checking all beds instead of just humanlike ones for room owner.
* [[Version/1.4.3523|1.4.3523]] - Added the storeroom role for rooms with lots of shelves.
* [[Biotech DLC]] release - Nursery, playroom, classroom, and deathrest chamber roles added.
* [[Anomaly DLC]] release - Containment cell and ceremonial chamber roles added.
* [[Version/1.6.4518|1.6.4518]] - Some production buildings now have a work speed penalty if they are not in the correct room.

== Notes ==
{{Reflist}}

[[Category:Game mechanics]]

Rooms

2026-01-29T18:53:54Z

Aelanna: Added note about floating point inaccuracies in space calculations determined via testing. This is a resolution for the request to change the "rather right" threshold to 12.6.

<span style="display:none;"><ref name="penalty">Work speed penalty of 80% if not placed in the room with the correct role.</ref></span>

{| align=center | {{Gameplay Nav}} |}

----

{{TOCright}}

A '''room''' is a space fully enclosed by impassable objects such as [[wall]]s, [[door]]s (open or closed), [[vent]]s, natural rock, or [[cooler]]s. Corners do not need to be filled in order to enclose a room.

== General ==
A room that's at least 75% [[roof]]ed is considered [[indoors]]. This distinction affects [[temperature]], [[Deterioration Rate]], [[Work Speed Factor]], and pawns' [[outdoors]] and indoors needs. {{Check Tag|Verify|Does it really affect all these stats, and how specifically?}}

An indoor room will remain an indoor room when its doors are open — even when they're held open permanently. [[Vac barrier]]s also enclose a room despite not being impassable. If a door is destroyed and the room is no longer enclosed, the room will instantly be considered outdoors.

The maximum size of a room is 36 [[#Map regions|map regions]]. The equivalent size in tiles varies based on the position and shape of the room, but as reference:
* The maximum area possible per room is 5,184 tiles (72x72).
* An empty 50x50 square room is the largest room that won't have issues with map regions.
* The more complex the shape of a room, the more likely it is to run into problems with map regions.
* Above this size, the area in question will be treated as a non-room indoors space.

=== Temperature ===
Indoor rooms can have a different temperature than the outside. Open [[door]]s, open [[vent]]s, or missing roof tiles will increase the rate at which heat is exchanged with the outdoors. For further information, see the [[temperature]] page.

The temperature of an outdoor room will always be identical to the outdoor temperature. If an indoor room has enough roof removed{{Check Tag|How much?}}, or stops being enclosed, it will ''instantly'' adopt the outdoor temperature.

== Roles ==
'''Room roles''' are assigned to a room based on the buildings they contain, such as a ''kitchen'' when containing an [[electric stove]] or a [[fueled stove]]. They determine whether a colonist is affected by all, some, or none of the room stats.

=== Summary ===
Certain room roles grant [[mood]]lets based on their [[Impressiveness]], which is affected by all four substats. To gain the moodlet, the room must be used by a pawn for the role's associated purpose (i.e., eating at a table for the dining room role or playing billiards for the rec room role). Despite the game displaying only one role, rooms can grant moodlets from multiple roles when used for that role. The moodlets are typically {{Check Tag|When not?}} applied when a colonist ''begins'' said activity in the room, and they last for 24 hours. {{Check Tag |Verify| What about deathresting? It uses a separate thought.}}

Buildings associated with hospitals, laboratories, and kitchens make direct use of the [[Cleanliness]] stat for their [[Work Speed Factor]].

Some room roles cannot have certain buildings inside without inflicting a mood penalty (i.e., [[Titles#Thrones and Bedrooms|throne rooms]] {{RoyaltyIcon}} and temples {{IdeologyIcon}} with [[Production|workstations]]).

Pawns also have separate needs for [[Beauty]] and [[Space]], which every room can fulfill. Unlike the room stats of the same name, these needs are checked within a certain radius from the pawn, as opposed to anywhere in the room. See those pages for further details.

=== Score calculation ===
For each room, every room role is given a score based on the buildings inside, and the role with the highest score is the one displayed. In the case of a tie, the earlier roles on the following table take priority.

For the purposes of room role scoring, the following are considered non-baby human beds: {{RoomRolesBuildingList|Bed-associated rooms}}.

=== List of roles ===
{| class="wikitable"
! Label
! Mood impact
! Related stats
! Score calculation logic
|-
| Room
| None
| None ||
* Returns a score of 0.99.
|-
| Bedroom <ref name="owner name">This role will have its owners' name added to its name.</ref>
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There are no human beds.
** There is at least 1 medical human bed or at least 1 prisoner human bed.
** There is more than 1 non-assigned human bed.
** There is at least 1 adult assigned and there are other pawns assigned that are not in its love cluster.<ref>A pawn's love cluster is all the other pawns that can be linked to the pawn through a chain of romantic relationships.</ref>
** There is at least 1 child assigned and there aren't any adults assigned that are a parent of the child.
* Returns 100,000 score otherwise.
|-
| Prison cell <ref name="owner name" />
| [[Mood#Situational RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There is more than 1 humanlike bed.
* Returns 170,000 score for a non-medical prisoner humanlike bed.
* Returns 100,000 score for a medical prisoner humanlike bed.
|-
| Dining room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 12 score per each one of the following: {{RoomRolesBuildingList|Dining room}}.
|-
| Rec room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 7 score per each one of the following: {{RoomRolesBuildingList|Rec room}}.
|-
| Hospital
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]], [[Room stats|Cleanliness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** There are no medical humanlike beds.
* Returns 100,000 score otherwise.
|-
| Laboratory
| No
| [[Room stats|Cleanliness]]
|
* Returns 60 score per each one of the following: {{RoomRolesBuildingList|Laboratory}}.
|-
| Workshop
| No
| None
|
* Returns 27 score per each one of the following: {{RoomRolesBuildingList|Workshop}}. The [[crafting spot]] does ''not'' count.
|-
| Storeroom
| No
| None
|
* Returns 1 score per each one of the following: {{RoomRolesBuildingList|Storeroom}}.
|-
| Barracks <ref name="owner name" />
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** The room is a valid bedroom.
* Returns 100,100 score for every non-medical humanlike bed otherwise.
|-
| Prison barracks <ref name="owner name" />
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There are less than 2 prisoner beds.
* Returns 100,100 score per non-medical prisoner bed and 50,001 per medical prisoner bed.
|-
| Kitchen
| No
| [[Room stats|Cleanliness]]
|
* Returns 28 score per production building that has at least 1 recipe that produces an edible result. The following fulfill the requirement: {{RoomRolesBuildingList|Kitchen}}. The [[brewery]], [[butcher spot]], and [[butcher table]] do ''not'' fulfill the requirement.
|-
| Tomb
| No
| None
|
* Returns 50 score per each one of the following: {{RoomRolesBuildingList|Tomb}}.
|-
| Barn
| No
| None
|
* Returns 7.6 score per non-humanlike bed, which are the following: {{RoomRolesBuildingList|Barn}}.
|-
| [[Throne room]] {{RoyaltyIcon}}
| No
| [[Impressiveness]]
|
* Returns 10,000 score if there is any one of the following: {{RoomRolesBuildingList|Throne room}}.
* Returns 0 score otherwise.
|-
| Temple {{IdeologyIcon}} <ref>This role changes to the ideoligion's set temple name.</ref>
| No
| None
|
* Returns -1 score if the [[Ideology DLC]] is not active.
* Returns 0 score if there are no altars with the colony's ideology.
* Returns 75 score per altar with the colony's ideology, with a minimum of 2,000 score. The following are considered altars: {{RoomRolesBuildingList|Temple}}.
|-
| Nursery {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 non-medical prisoner bed or at least 1 non-baby bed.
** There are less than 2 baby beds.
* Returns 100,200 score per baby bed. The following are considered baby beds: {{RoomRolesBuildingList|Nursery}}.
|-
| Playroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 humanlike bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Playroom}}.
|-
| Classroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 human bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Classroom}}.
|-
| Deathrest chamber {{BiotechIcon}}
| Yes
| [[Room stats|Impressiveness]]
|
* Returns 100 score per [[deathrest casket]] {{BiotechIcon}} and 50 score per [[deathrest accelerator]] {{BiotechIcon}}, [[glucosoid pump]] {{BiotechIcon}}, [[hemogen amplifier]] {{BiotechIcon}}, [[hemopump]] {{BiotechIcon}}, or [[psychofluid pump]] {{BiotechIcon}}.
|-
| Containment cell {{AnomalyIcon}}
| None
| None
|
* Returns 100 score per [[holding platform]] {{AnomalyIcon}} or [[holding spot]] {{AnomalyIcon}} and 50 score per [[bioferrite harvester]] {{AnomalyIcon}}, [[electric inhibitor]] {{AnomalyIcon}}, or [[electroharvester]] {{AnomalyIcon}}.
|-
| Ceremonial chamber {{AnomalyIcon}}
| None
| None
|
* Returns 200 score per each one of the following: {{RoomRolesBuildingList|Ceremonial chamber}}.
|-
|}

Other pieces of [[furniture]] not mentioned, such as [[chair|chairs]], are not considered for score calculation.

== Stats ==
[[File:quality preview.png|300px|right]]
'''Room stats''' are values of a room that passively affect both [[thought]]s about the room itself and some events and activities that take place within. These include [[Impressiveness]], which is calculated from four composite stats: [[Wealth]], [[Beauty]], [[Space]], and [[Cleanliness]]. These base stats are automatically calculated from [[buildings]], [[floor]]ing, [[filth]], the room's perimeter, and items within the room.

Room stats can be inspected with the room stats display, which can be toggled with a button in the lower right corner of the screen or a hotkey (''G'' by default). Additional information can also be viewed by holding down the ''Alt'' key.

Room stats affect the following:
* Medical treatment quality (Cleanliness)
* Research speed (Cleanliness)
* [[Food poisoning]] chance in prepared meals (Cleanliness)
* [[Mood#Room_stats|Mood]] of the people using them (Impressiveness)

The following traits are affected by room stats:
* [[Greedy]] - Decrease without sufficiently Impressive bedroom.
* [[Jealous]] - Decrease if anyone has a noticeably better bedroom. {{Check Tag|How much?}}
* [[Ascetic]] - Decrease if room is too Impressive. Increase if bedroom is dull or worse.

=== Impressiveness ===
The value for '''Impressiveness''' is based on the four other room stats ('''Wealth''', '''Beauty''', '''Space''', and '''Cleanliness''').

The mood effects from the room depend on the Impressiveness level, and not on the precise value. That value is rounded ''down'' to the nearest whole number, and a label (or "level") of Impressiveness will be given to the room, according to the table below. This level is used to apply the relevant thought, positive or negative.

The exact mood effects depend on the [[Room#Roles|room role]], with different rooms having different values at each level. For more information, see [[Mood#Room stats|this section of the Mood page]]{{Check Tag|Outdated link}} For bedrooms, dining rooms, and rec rooms, the effects are as follows:{{Check Tag|Verify table|Add values for other room types}}

::{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! Mood impact
|-
| < 20
| awful
| {{Bad|-2}} (bedrooms only)
|-
| >= 20 and < 30
| dull
| ''none''
|-
| >= 30 and < 40
| mediocre
| ''none''
|-
| >= 40 and < 50
| decent
| {{Good|+2}}
|-
| >= 50 and < 65
| slightly impressive
| {{Good|+3}}
|-
| >= 65 and < 85
| somewhat impressive
| {{Good|+4}}
|-
| >= 85 and < 120
| very impressive
| {{Good|+5}}
|-
| >= 120 and < 170
| extremely impressive
| {{Good|+6}}
|-
| >= 170 and < 240
| unbelievably impressive
| {{Good|+7}}
|-
| >= 240
| wondrously impressive
| {{Good|+8}}
|}

==== Guidelines ====

Since the impressiveness calculation (explained below) is fairly involved, it is not practical to predict impressiveness levels in an actual game. However, the following rules of thumb can be applied:

* '''Keep all four room stats equally in mind.''' There is a heavy weighting towards whichever stat is weakest, which is counted as much as all three other stats combined. For example, having a masterpiece work of art in a large room (high ''wealth'', ''space'' and ''beauty'') is not very effective if the floor is covered in vomit and animal filth (low ''cleanliness''). It is quite difficult to compensate for one low stat by raising the other three.

* '''Making a particularly small room ''impressive'' is difficult.''' Room size is a limiting factor for Impressiveness. If you want to make the room "very impressive", it should have a space of at least around 25 (which still counts as "rather tight" in the game). E.g. a furnished bedroom with a 5x5 or 4×6 footprint would be fine, and a little smaller could still work, but it would be a challenge to get there with a 4x4 room. Note that any naturally "large" rooms like hallways, lobbies, recreation halls etc. will never run into this limitation at all.

* '''Cleanliness matters'''. Since the level of impressiveness is what counts, and there are sharp thresholds separating the levels, even a minute change of any of the values can have a strong effect. This is usually due to ''cleanliness'' changing (because the other factors are pretty much fixed); even a single speck of dirt on the floor can result in major [[mood]] changes. Make sure that the room is not too close to a level threshold, and keep it clean.

* '''Do not go overboard'''. There are sharply diminishing returns from increasing any room stat. Increasing any of the stats has dramatically diminishing returns with regards to impressiveness. It is not worth putting a lot of resources into any of the stats beyond a point.*
:: (* Not unless you care about the stat for other reasons; "room impressiveness" is not the only stat that can affect [[mood]]. Beauty, among others, has its own value.)

==== Formula ====
The actual formula for calculating impressiveness involves multiple steps, starting with the four room statistics (wealth, beauty, space and cleanliness) and resulting in a single integer value ''impressiveness''.

The calculation is done in several steps:
# Convert each stat into natural units, so that typical in-game stats end up in a range of comparable single digit values.
# Curve values beyond (-1, 1) using a natural logarithm.
# Average the four stats into an impressiveness score, weighted towards the lowest one
# Soft-cap the result according to the space of the room.

<div class="mw-customtoggle-EXImpressivness" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Detailed formula:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-EXImpressivness">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
===== Base values =====
Firstly, all four raw stats are scaled individually by applying a factor, deriving the ''base contribution'' for each stat:

: '''W'''<sub>b</sub> = ''wealth'' ÷ 1500
: '''B'''<sub>b</sub> = ''beauty'' ÷ 3
: '''S'''<sub>b</sub> = ''space'' ÷ 125
: '''C'''<sub>b</sub> = 1 + (''cleanliness'' ÷ 2.5)

===== Modified values =====
These base values are now modified if they lie outside the range (−1, 1), by applying the ''natural logarithm'' as follows: {{Check Tag|Add image|An image would be quite useful because the modified values are actually very visually intuitive despite the formula's complexity}}
m = 1 + ln(b) (if b >= 1)
m = [1 + ln(−b)] × −1 (if b <= −1)
(This is symmetrical for positive and negative values).

===== Impressiveness score =====
These modified values are then combined to give the ''impressiveness'' score as follows.

Take a weighted sum of the average of the values and the smallest of the values:
I = (65 × ('''W'''<sub>m</sub> + '''B'''<sub>m</sub> + '''S'''<sub>m</sub> + '''C'''<sub>m</sub>) ÷ 4) + (35 × min('''W'''<sub>m</sub>, '''B'''<sub>m</sub>, '''S'''<sub>m</sub>, '''C'''<sub>m</sub>))
This means that the smallest of the values contributes 51.25%, just over half, while the other three values each contribute 16.25%, or 48.75% combined.

As a final step we compare this impressiveness value to the ''spaciousness'' of the room:
S' = 500 × S<sub>m</sub>
If I > S', then
I' = 0.25 × I + 0.75 × S'
else
I' = I (no change)

This means a room's max impressiveness is soft-capped to 500% of their space score. However, this specific step is only relevant for very small, disproportionately luxurious rooms. Even a 60-space room (S = 0.5) will incur no penalty up to 240 impressiveness, enough to clear the highest bracket ("wondrously impressive"), and a 30-space room (S = 0.24) already reaches "extremely impressive" with no penalty.

===== Takeaways =====
It can be useful to think of impressiveness as a percentage value composed of four categories; a score of 1 in each category corresponds to 100 impressiveness, while values above 1 stop giving "fair" (ie. linear) returns. One unit of each stat is equivalent to each the following:
* ''Wealth'' of 1,500
* ''Beauty'' of 3
* ''Cleanliness'' of 0 (i.e. when using any cleanliness enhancers)
* ''Space'' of 125
Above these values, it begins to become more economical to invest attention in other stats. A "standard bedroom" of size 4×6, carpeted and containing bed, dresser, end table, lamp and plant pot will still have plenty of leeway in all categories (except cleanliness, which is at a natural 0 for a cleaned room); in this case, you will usually proceed by putting a sculpture or high quality armchair in the room, increasing beauty and wealth.

Furthermore, observe that the factors (i.e., modified values) for ''wealth'' and ''beauty'' will often be well above 1, but ''cleanliness'' and ''space'' usually lower than 1. Unless the room is "very spacious", or close to it, the decisive factor will thus be ''space'', then ''cleanliness''. In fact, even a well-cleaned room can never have a value over C = 1 (0 cleanliness; perfectly clean) or C = 1.215 (0.6 cleanliness; sterile), meaning rooms above ~100-120 impressiveness will ''always'' be bottlenecked by their cleanliness score. This makes "very impressive" (85-120 impressiveness) a natural set point for many rooms.

===== Example =====
Start with a room with a ''wealth'' of 3000, ''space'' of 25, ''cleanliness'' of 0, beauty of 3.
: '''W'''<sub>b</sub> = ''3000'' ÷ 1500 = 2, but this is curved to 1 + ln(2) = '''1.69'''
: '''B'''<sub>b</sub> = ''3'' ÷ 3 = 1
: '''S'''<sub>b</sub> = ''25'' ÷ 125 = 0.2
: '''C'''<sub>b</sub> = 1 + (''0'' ÷ 2.5) = 1

This makes the average score (1.69 + 1 + 0.2 + 1) ÷ 4) = 0.97 and the lowest score 0.2 (space).

From the above numbers, we can calculate the base Impressiveness
: I = (65 × 0.97) + (35 × 0.2)
: I = 63 + 7
: I = 70 (70.21 unrounded)
Now, I < 500 × '''S'''<sub>m</sub> (70 < 100), so there is no space penalty. Therefore, the reported Impressiveness of the room is 70 or "somewhat impressive"

If we were to increase the ''wealth'' of the above room by 6000 (4 units), our W<sub>m</sub> would become 6 -> 1 + ln(6) = 2.79 (+1.1 increase). Wealth wasn't the lowest stat, so this would only improve impressiveness by 1.1*16.25% = 17.9%, resulting in a score of 88 or "very impressive"

If we were to increase the original room's space by 10 units instead, '''S'''<sub>m</sub> becomes 0.28 (0.08 increase). Increasing the bottleneck stat results in a change of 0.08*51.25% = 4.1%, or 74 total impressiveness or "somewhat impressive"
</div></div>

=== Wealth ===
This is the sum of the [[Market Value]] of all items in the room and all walls and doors surrounding the room. Walls, doors, columns and animal flaps in the outer corner count as well. The value of [[power conduit]]s in walls ''is'' also included, however, for some reason building or deconstructing a conduit doesn't immediately update room wealth. Only if wealth is recalculated for some other reason, is the value of the conduits included. The same is true when building a column in the outer corner of the wall.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < 500
| impoverished
|-
| >= 500 and < 700
| somewhat poor
|-
| >= 700 and < 2000
| mediocre
|-
| >= 2000 and < 4000
| somewhat rich
|-
| >= 4000 and < 10000
| rich
|-
| >= 10000 and < 40000
| luxurious
|-
| >= 40000 and < 100000
| very luxurious
|-
| >= 100000 and < 1000000
| extremely luxurious
|-
| >= 1000000
| unbelievably luxurious
|}

=== Beauty ===
This is the average environmental beauty of the room including its walls and doors with a penalty for small rooms. Walls, doors and columns in the outer corner count as well. Building or deconstructing a column in the outer corner doesn't trigger a recalculation however. Floor tiles underneath walls and doors have no influence.

Room beauty is calculated as:

<pre>TotalBeauty = sum(beauty for each internal cell) + sum(beauty for each adjacent cell)
WeightedSize = size if (size > 40) else (20 + size / 2)
RoomBeauty = TotalBeauty / WeightedSize</pre>

This means that all rooms with less than 40 internal space will have their beauty penalised.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < -3.5
| hideous
|-
| >= -3.5 and < 0
| ugly
|-
| >= 0 and < 2.4
| neutral
|-
| >= 2.4 and < 5
| pretty
|-
| >= 5 and < 15
| beautiful
|-
| >= 15 and < 50
| very beautiful
|-
| >= 50 and < 100
| extremely beautiful
|-
| >= 100
| unbelievably beautiful

|}

=== Space ===
Indicates how much free space is available in the room. A room's Space score is 1.4 times the number of tiles in the room. Objects that prevent a pawn from standing in a space will decrease the available space in the room by 0.9 per tile the object covers. Thus, an occupied tile contributes a total of 0.5 to space. Objects that reduce space include beds, tables, workbenches, lamps, and heaters. Stools and chairs do not reduce space.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! typical size*
|-
| < 12.5
| cramped
| 3x4 or smaller*
|-
| >= 12.5 and < 29
| rather tight
| 3x6, 4x5*
|-
| >= 29 and < 55
| average-sized
| 4x7, 5x6*
|-
| >= 55 and < 70
| somewhat spacious
|-
| >= 70 and < 130
| quite spacious
|-
| >= 130 and < 349.5
| very spacious
|-
| >= 349.5
| extremely spacious
|}
: (* These are "safe" approximations; as described, the items placed <u>in</u> the room can greatly reduce the effective size. For example, an empty 5x5 room has space (25 x 1.4 =) 35, easily "average" - when empty. However, placing just one bed (2 tiles), one table (2 tiles), a light, a heater, a plant pot and one artwork (1 tile each, a chair is "free") in that room reduces the effective space by -7.2 (= 8 tiles x .9), and the effective space is now 27.8, "rather tight".)
: (* Due to floating point inaccuracies, sometimes a room that is right on a threshold may randomly count for one category or the other. For example, a room with 5 standable tiles and 11 walkable but non-standable tiles should come out to exactly 12.5 score, but may result in either "cramped" or "rather tight". It's safest to not rely on exact values.)

Note, that space of the room affects only its impressiveness. Careful to not confuse with Pawn's [[space]] need.

=== Cleanliness ===
This stat affects [[Surgery_Success_Chance_Factor#Room_Cleanliness_Multiplier|Surgery Success Chance]], [[Research#Research speed|research speed]], the chance that cooked meals will cause [[food poisoning]], and gene [[Assembly Speed Factor]].{{BiotechIcon}} A room's cleanliness is the average cleanliness score of all tiles in the room. It is determined by the type of [[floor]]ing, the presence of any [[filth]], and the cleanliness value of some furniture such as the [[butcher table]] and the [[stonecutter's table]]. Note that the type of [[floor]] under a door doesn't count for Cleanliness, but filth under a door does count.

<div style=display:inline-grid>
:::{| class="wikitable"
! Room Cleanliness
! Description
|-
| < -1.1
| very dirty
|-
| >= -1.1 and < -0.4
| dirty
|-
| >= -0.4 and < -0.05
| slightly dirty
|-
| >= -0.05 and < 0.4
| clean
|-
| >= 0.4
| sterile
|}
</div>
<div style=display:inline-grid>
:{| class="wikitable"
|-
! Surface
! Cleanliness<br/>Value
|-
|[[Void metal ]]{{AnomalyIcon}} || 1
|-
| [[Sterile tile]] floor || 0.6
|-
| [[Steel tile|Steel]], [[Silver tile|Silver]] or [[Gold tile|Gold]] floor || 0.2
|-
|[[Bioferrite plate]]{{AnomalyIcon}} || 0.2
|-
| all other constructed [[floor]]ing<nowiki>;</nowiki> [[Bridge]]s || 0
|-
| Natural stone ([[Rough stone|rough]] or [[Smooth stone|smoothed]]) || 0
|-
| [[Straw matting]] || -0.1
|-
| all other [[Environment#Terrain|natural surfaces]] (soil, gravel, etc.) || -1
|-
| [[Marsh]], [[Marshy soil]], [[Mud]], [[Broken asphalt]] || -2
|-
| [[Chunk]]s || -2
|-
|[[Flesh]]{{AnomalyIcon}} || -3
|-
| [[Filth|Dirt, rubble, all other filth]] || -5
|-
| [[Filth|Blood]] || -10
|-
| [[Filth|Insect blood, vomit, fuel puddle]] || -15
|-
| [[Filth|Corpsebile]] || -20
|}
</div>

Using "Toggle the beauty display" can help locate filth in a given room, which typically stands out due to its negative beauty.

== Map regions ==
Upon map generation, the map is divided into chunks of 12x12 squares called map regions. Each region requires a contiguous area and will be subdivided otherwise. Under no circumstance will a region extend beyond the initial 12x12 grid. Impassable buildings (both natural and artificial) are not considered as part of any map region for this purpose and will subdivide existing map regions accordingly. Regions will fuse when possible. Map regions are used for several calculations and can be seen in game via the debug option "Draw Regions".

<div class="mw-customtoggle-myDivision" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Some additional notes:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
* Impassable buildings are never part of any map region.
** Impassable non-walls (ex: [[Ship engine]]) may create a "red" temporal map region on construction that will be removed once anything else is build/destroyed.
* Impassable terrain creates map regions confined to its extension.
** These regions don't interact with the regular ones, but otherwise follow the stated rules.
* Passable buildings, such as [[fence]]s and [[barricade]]s, create map regions along their extension.
** These "fence" regions won't interact with other kinds, but otherwise follow the stated rules.
* Doors have unique behavior
** Single tile doors create a 3 tile map region centered on the doors' tile, following the door's orientation, that overlaps with other map regions.
*** Impassable objects will delete the overlapping section, no interaction otherwise.
** Double tile doors create 2 map regions, 1 for each of its tiles.
** The map regions created by doors don't interact with any other, not even each other.
* The grid defining regions is drawn from the bottom-left of the map row by row.
</div></div>

== Version history ==
* [[Version/0.12.906|0.12.906]] - Added.
* 1.1 - Added room stats gizmo, which displays the stats of the room containing a selected building, at a glance.
* [[Royalty DLC]] release - Throne room role added.
* [[Ideology DLC]] release - Temple room role added.
* [[Version/1.3.3072|1.3.3072]] - Fix: Checking all beds instead of just humanlike ones for room owner.
* [[Version/1.4.3523|1.4.3523]] - Added the storeroom role for rooms with lots of shelves.
* [[Biotech DLC]] release - Nursery, playroom, classroom, and deathrest chamber roles added.
* [[Anomaly DLC]] release - Containment cell and ceremonial chamber roles added.
* [[Version/1.6.4518|1.6.4518]] - Some production buildings now have a work speed penalty if they are not in the correct room.

== Notes ==
{{Reflist}}

[[Category:Game mechanics]]

Rooms

2026-01-27T19:30:57Z

Aelanna: I rejected your edit because it is straight-up incorrect and doesn't match the game's code. If you have evidence to the contrary, please come talk to me on Discord.

<span style="display:none;"><ref name="penalty">Work speed penalty of 80% if not placed in the room with the correct role.</ref></span>

{| align=center | {{Gameplay Nav}} |}

----

{{TOCright}}

A '''room''' is a space fully enclosed by impassable objects such as [[wall]]s, [[door]]s (open or closed), [[vent]]s, natural rock, or [[cooler]]s. Corners do not need to be filled in order to enclose a room.

== General ==
A room that's at least 75% [[roof]]ed is considered [[indoors]]. This distinction affects [[temperature]], [[Deterioration Rate]], [[Work Speed Factor]], and pawns' [[outdoors]] and indoors needs. {{Check Tag|Verify|Does it really affect all these stats, and how specifically?}}

An indoor room will remain an indoor room when its doors are open — even when they're held open permanently. [[Vac barrier]]s also enclose a room despite not being impassable. If a door is destroyed and the room is no longer enclosed, the room will instantly be considered outdoors.

The maximum size of a room is 36 [[#Map regions|map regions]]. The equivalent size in tiles varies based on the position and shape of the room, but as reference:
* The maximum area possible per room is 5,184 tiles (72x72).
* An empty 50x50 square room is the largest room that won't have issues with map regions.
* The more complex the shape of a room, the more likely it is to run into problems with map regions.
* Above this size, the area in question will be treated as a non-room indoors space.

=== Temperature ===
Indoor rooms can have a different temperature than the outside. Open [[door]]s, open [[vent]]s, or missing roof tiles will increase the rate at which heat is exchanged with the outdoors. For further information, see the [[temperature]] page.

The temperature of an outdoor room will always be identical to the outdoor temperature. If an indoor room has enough roof removed{{Check Tag|How much?}}, or stops being enclosed, it will ''instantly'' adopt the outdoor temperature.

== Roles ==
'''Room roles''' are assigned to a room based on the buildings they contain, such as a ''kitchen'' when containing an [[electric stove]] or a [[fueled stove]]. They determine whether a colonist is affected by all, some, or none of the room stats.

=== Summary ===
Certain room roles grant [[mood]]lets based on their [[Impressiveness]], which is affected by all four substats. To gain the moodlet, the room must be used by a pawn for the role's associated purpose (i.e., eating at a table for the dining room role or playing billiards for the rec room role). Despite the game displaying only one role, rooms can grant moodlets from multiple roles when used for that role. The moodlets are typically {{Check Tag|When not?}} applied when a colonist ''begins'' said activity in the room, and they last for 24 hours. {{Check Tag |Verify| What about deathresting? It uses a separate thought.}}

Buildings associated with hospitals, laboratories, and kitchens make direct use of the [[Cleanliness]] stat for their [[Work Speed Factor]].

Some room roles cannot have certain buildings inside without inflicting a mood penalty (i.e., [[Titles#Thrones and Bedrooms|throne rooms]] {{RoyaltyIcon}} and temples {{IdeologyIcon}} with [[Production|workstations]]).

Pawns also have separate needs for [[Beauty]] and [[Space]], which every room can fulfill. Unlike the room stats of the same name, these needs are checked within a certain radius from the pawn, as opposed to anywhere in the room. See those pages for further details.

=== Score calculation ===
For each room, every room role is given a score based on the buildings inside, and the role with the highest score is the one displayed. In the case of a tie, the earlier roles on the following table take priority.

For the purposes of room role scoring, the following are considered non-baby humanlike beds: {{RoomRolesBuildingList|Bed-associated rooms}}.

=== List of roles ===
{| class="wikitable"
! Label
! Mood impact
! Related stats
! Score calculation logic
|-
| Room
| None
| None ||
* Returns a score of 0.99.
|-
| Bedroom <ref name="owner name">This role will have its owners' name added to its name.</ref>
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There are no humanlike beds.
** There is at least 1 medical humanlike bed or at least 1 prisoner humanlike bed.
** There is more than 1 non-assigned humanlike bed.
** There is at least 1 adult assigned and there are other pawns assigned that are not in its love cluster.<ref>A pawn's love cluster is all the other pawns that can be linked to the pawn through a chain of romantic relationships.</ref>
** There is at least 1 child assigned and there aren't any adults assigned that are a parent of the child.
* Returns 100,000 score otherwise.
|-
| Prison cell <ref name="owner name" />
| [[Mood#Situational RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There is more than 1 humanlike bed.
* Returns 170,000 score for a non-medical prisoner humanlike bed.
* Returns 100,000 score for a medical prisoner humanlike bed.
|-
| Dining room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 12 score per each one of the following: {{RoomRolesBuildingList|Dining room}}.
|-
| Rec room
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 7 score per each one of the following: {{RoomRolesBuildingList|Rec room}}.
|-
| Hospital
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]], [[Room stats|Cleanliness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** There are no medical humanlike beds.
* Returns 100,000 score otherwise.
|-
| Laboratory
| No
| [[Room stats|Cleanliness]]
|
* Returns 60 score per each one of the following: {{RoomRolesBuildingList|Laboratory}}.
|-
| Workshop
| No
| None
|
* Returns 27 score per each one of the following: {{RoomRolesBuildingList|Workshop}}. The [[crafting spot]] does ''not'' count.
|-
| Storeroom
| No
| None
|
* Returns 1 score per each one of the following: {{RoomRolesBuildingList|Storeroom}}.
|-
| Barracks <ref name="owner name" />
| [[Mood#Room Stats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 prisoner humanlike bed.
** The room is a valid bedroom.
* Returns 100,100 score for every non-medical humanlike bed otherwise.
|-
| Prison barracks <ref name="owner name" />
| [[Mood#Situation RoomStats|Yes]]
| [[Impressiveness]]
|
* Returns 0 score if any of the following is true:
** There is at least 1 non-prisoner humanlike bed.
** There are less than 2 prisoner beds.
* Returns 100,100 score per non-medical prisoner bed and 50,001 per medical prisoner bed.
|-
| Kitchen
| No
| [[Room stats|Cleanliness]]
|
* Returns 28 score per production building that has at least 1 recipe that produces an edible result. The following fulfill the requirement: {{RoomRolesBuildingList|Kitchen}}. The [[brewery]], [[butcher spot]], and [[butcher table]] do ''not'' fulfill the requirement.
|-
| Tomb
| No
| None
|
* Returns 50 score per each one of the following: {{RoomRolesBuildingList|Tomb}}.
|-
| Barn
| No
| None
|
* Returns 7.6 score per non-humanlike bed, which are the following: {{RoomRolesBuildingList|Barn}}.
|-
| [[Throne room]] {{RoyaltyIcon}}
| No
| [[Impressiveness]]
|
* Returns 10,000 score if there is any one of the following: {{RoomRolesBuildingList|Throne room}}.
* Returns 0 score otherwise.
|-
| Temple {{IdeologyIcon}} <ref>This role changes to the ideoligion's set temple name.</ref>
| No
| None
|
* Returns -1 score if the [[Ideology DLC]] is not active.
* Returns 0 score if there are no altars with the colony's ideology.
* Returns 75 score per altar with the colony's ideology, with a minimum of 2,000 score. The following are considered altars: {{RoomRolesBuildingList|Temple}}.
|-
| Nursery {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 non-medical prisoner bed or at least 1 non-baby bed.
** There are less than 2 baby beds.
* Returns 100,200 score per baby bed. The following are considered baby beds: {{RoomRolesBuildingList|Nursery}}.
|-
| Playroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 humanlike bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Playroom}}.
|-
| Classroom {{BiotechIcon}}
| No
| None
|
* Returns 0 score if any of the following is true:
** The [[Biotech DLC]] is not active.
** There is at least 1 human bed in the room.
* Returns 8 score per each one of the following: {{RoomRolesBuildingList|Classroom}}.
|-
| Deathrest chamber {{BiotechIcon}}
| Yes
| [[Room stats|Impressiveness]]
|
* Returns 100 score per [[deathrest casket]] {{BiotechIcon}} and 50 score per [[deathrest accelerator]] {{BiotechIcon}}, [[glucosoid pump]] {{BiotechIcon}}, [[hemogen amplifier]] {{BiotechIcon}}, [[hemopump]] {{BiotechIcon}}, or [[psychofluid pump]] {{BiotechIcon}}.
|-
| Containment cell {{AnomalyIcon}}
| None
| None
|
* Returns 100 score per [[holding platform]] {{AnomalyIcon}} or [[holding spot]] {{AnomalyIcon}} and 50 score per [[bioferrite harvester]] {{AnomalyIcon}}, [[electric inhibitor]] {{AnomalyIcon}}, or [[electroharvester]] {{AnomalyIcon}}.
|-
| Ceremonial chamber {{AnomalyIcon}}
| None
| None
|
* Returns 200 score per each one of the following: {{RoomRolesBuildingList|Ceremonial chamber}}.
|-
|}

Other pieces of [[furniture]] not mentioned, such as [[chair|chairs]], are not considered for score calculation.

== Stats ==
[[File:quality preview.png|300px|right]]
'''Room stats''' are values of a room that passively affect both [[thought]]s about the room itself and some events and activities that take place within. These include [[Impressiveness]], which is calculated from four composite stats: [[Wealth]], [[Beauty]], [[Space]], and [[Cleanliness]]. These base stats are automatically calculated from [[buildings]], [[floor]]ing, [[filth]], the room's perimeter, and items within the room.

Room stats can be inspected with the room stats display, which can be toggled with a button in the lower right corner of the screen or a hotkey (''G'' by default). Additional information can also be viewed by holding down the ''Alt'' key.

Room stats affect the following:
* Medical treatment quality (Cleanliness)
* Research speed (Cleanliness)
* [[Food poisoning]] chance in prepared meals (Cleanliness)
* [[Mood#Room_stats|Mood]] of the people using them (Impressiveness)

The following traits are affected by room stats:
* [[Greedy]] - Decrease without sufficiently Impressive bedroom.
* [[Jealous]] - Decrease if anyone has a noticeably better bedroom. {{Check Tag|How much?}}
* [[Ascetic]] - Decrease if room is too Impressive. Increase if bedroom is dull or worse.

=== Impressiveness ===
The value for '''Impressiveness''' is based on the four other room stats ('''Wealth''', '''Beauty''', '''Space''', and '''Cleanliness''').

The mood effects from the room depend on the Impressiveness level, and not on the precise value. That value is rounded ''down'' to the nearest whole number, and a label (or "level") of Impressiveness will be given to the room, according to the table below. This level is used to apply the relevant thought, positive or negative.

The exact mood effects depend on the [[Room#Roles|room role]], with different rooms having different values at each level. For more information, see [[Mood#Room stats|this section of the Mood page]]{{Check Tag|Outdated link}} For bedrooms, dining rooms, and rec rooms, the effects are as follows:{{Check Tag|Verify table|Add values for other room types}}

::{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! Mood impact
|-
| < 20
| awful
| {{Bad|-2}} (bedrooms only)
|-
| >= 20 and < 30
| dull
| ''none''
|-
| >= 30 and < 40
| mediocre
| ''none''
|-
| >= 40 and < 50
| decent
| {{Good|+2}}
|-
| >= 50 and < 65
| slightly impressive
| {{Good|+3}}
|-
| >= 65 and < 85
| somewhat impressive
| {{Good|+4}}
|-
| >= 85 and < 120
| very impressive
| {{Good|+5}}
|-
| >= 120 and < 170
| extremely impressive
| {{Good|+6}}
|-
| >= 170 and < 240
| unbelievably impressive
| {{Good|+7}}
|-
| >= 240
| wondrously impressive
| {{Good|+8}}
|}

==== Guidelines ====

Since the impressiveness calculation (explained below) is fairly involved, it is not practical to predict impressiveness levels in an actual game. However, the following rules of thumb can be applied:

* '''Keep all four room stats equally in mind.''' There is a heavy weighting towards whichever stat is weakest, which is counted as much as all three other stats combined. For example, having a masterpiece work of art in a large room (high ''wealth'', ''space'' and ''beauty'') is not very effective if the floor is covered in vomit and animal filth (low ''cleanliness''). It is quite difficult to compensate for one low stat by raising the other three.

* '''Making a particularly small room ''impressive'' is difficult.''' Room size is a limiting factor for Impressiveness. If you want to make the room "very impressive", it should have a space of at least around 25 (which still counts as "rather tight" in the game). E.g. a furnished bedroom with a 5x5 or 4×6 footprint would be fine, and a little smaller could still work, but it would be a challenge to get there with a 4x4 room. Note that any naturally "large" rooms like hallways, lobbies, recreation halls etc. will never run into this limitation at all.

* '''Cleanliness matters'''. Since the level of impressiveness is what counts, and there are sharp thresholds separating the levels, even a minute change of any of the values can have a strong effect. This is usually due to ''cleanliness'' changing (because the other factors are pretty much fixed); even a single speck of dirt on the floor can result in major [[mood]] changes. Make sure that the room is not too close to a level threshold, and keep it clean.

* '''Do not go overboard'''. There are sharply diminishing returns from increasing any room stat. Increasing any of the stats has dramatically diminishing returns with regards to impressiveness. It is not worth putting a lot of resources into any of the stats beyond a point.*
:: (* Not unless you care about the stat for other reasons; "room impressiveness" is not the only stat that can affect [[mood]]. Beauty, among others, has its own value.)

==== Formula ====
The actual formula for calculating impressiveness involves multiple steps, starting with the four room statistics (wealth, beauty, space and cleanliness) and resulting in a single integer value ''impressiveness''.

The calculation is done in several steps:
# Convert each stat into natural units, so that typical in-game stats end up in a range of comparable single digit values.
# Curve values beyond (-1, 1) using a natural logarithm.
# Average the four stats into an impressiveness score, weighted towards the lowest one
# Soft-cap the result according to the space of the room.

<div class="mw-customtoggle-EXImpressivness" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Detailed formula:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-EXImpressivness">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
===== Base values =====
Firstly, all four raw stats are scaled individually by applying a factor, deriving the ''base contribution'' for each stat:

: '''W'''<sub>b</sub> = ''wealth'' ÷ 1500
: '''B'''<sub>b</sub> = ''beauty'' ÷ 3
: '''S'''<sub>b</sub> = ''space'' ÷ 125
: '''C'''<sub>b</sub> = 1 + (''cleanliness'' ÷ 2.5)

===== Modified values =====
These base values are now modified if they lie outside the range (−1, 1), by applying the ''natural logarithm'' as follows: {{Check Tag|Add image|An image would be quite useful because the modified values are actually very visually intuitive despite the formula's complexity}}
m = 1 + ln(b) (if b >= 1)
m = [1 + ln(−b)] × −1 (if b <= −1)
(This is symmetrical for positive and negative values).

===== Impressiveness score =====
These modified values are then combined to give the ''impressiveness'' score as follows.

Take a weighted sum of the average of the values and the smallest of the values:
I = (65 × ('''W'''<sub>m</sub> + '''B'''<sub>m</sub> + '''S'''<sub>m</sub> + '''C'''<sub>m</sub>) ÷ 4) + (35 × min('''W'''<sub>m</sub>, '''B'''<sub>m</sub>, '''S'''<sub>m</sub>, '''C'''<sub>m</sub>))
This means that the smallest of the values contributes 51.25%, just over half, while the other three values each contribute 16.25%, or 48.75% combined.

As a final step we compare this impressiveness value to the ''spaciousness'' of the room:
S' = 500 × S<sub>m</sub>
If I > S', then
I' = 0.25 × I + 0.75 × S'
else
I' = I (no change)

This means a room's max impressiveness is soft-capped to 500% of their space score. However, this specific step is only relevant for very small, disproportionately luxurious rooms. Even a 60-space room (S = 0.5) will incur no penalty up to 240 impressiveness, enough to clear the highest bracket ("wondrously impressive"), and a 30-space room (S = 0.24) already reaches "extremely impressive" with no penalty.

===== Takeaways =====
It can be useful to think of impressiveness as a percentage value composed of four categories; a score of 1 in each category corresponds to 100 impressiveness, while values above 1 stop giving "fair" (ie. linear) returns. One unit of each stat is equivalent to each the following:
* ''Wealth'' of 1,500
* ''Beauty'' of 3
* ''Cleanliness'' of 0 (i.e. when using any cleanliness enhancers)
* ''Space'' of 125
Above these values, it begins to become more economical to invest attention in other stats. A "standard bedroom" of size 4×6, carpeted and containing bed, dresser, end table, lamp and plant pot will still have plenty of leeway in all categories (except cleanliness, which is at a natural 0 for a cleaned room); in this case, you will usually proceed by putting a sculpture or high quality armchair in the room, increasing beauty and wealth.

Furthermore, observe that the factors (i.e., modified values) for ''wealth'' and ''beauty'' will often be well above 1, but ''cleanliness'' and ''space'' usually lower than 1. Unless the room is "very spacious", or close to it, the decisive factor will thus be ''space'', then ''cleanliness''. In fact, even a well-cleaned room can never have a value over C = 1 (0 cleanliness; perfectly clean) or C = 1.215 (0.6 cleanliness; sterile), meaning rooms above ~100-120 impressiveness will ''always'' be bottlenecked by their cleanliness score. This makes "very impressive" (85-120 impressiveness) a natural set point for many rooms.

===== Example =====
Start with a room with a ''wealth'' of 3000, ''space'' of 25, ''cleanliness'' of 0, beauty of 3.
: '''W'''<sub>b</sub> = ''3000'' ÷ 1500 = 2, but this is curved to 1 + ln(2) = '''1.69'''
: '''B'''<sub>b</sub> = ''3'' ÷ 3 = 1
: '''S'''<sub>b</sub> = ''25'' ÷ 125 = 0.2
: '''C'''<sub>b</sub> = 1 + (''0'' ÷ 2.5) = 1

This makes the average score (1.69 + 1 + 0.2 + 1) ÷ 4) = 0.97 and the lowest score 0.2 (space).

From the above numbers, we can calculate the base Impressiveness
: I = (65 × 0.97) + (35 × 0.2)
: I = 63 + 7
: I = 70 (70.21 unrounded)
Now, I < 500 × '''S'''<sub>m</sub> (70 < 100), so there is no space penalty. Therefore, the reported Impressiveness of the room is 70 or "somewhat impressive"

If we were to increase the ''wealth'' of the above room by 6000 (4 units), our W<sub>m</sub> would become 6 -> 1 + ln(6) = 2.79 (+1.1 increase). Wealth wasn't the lowest stat, so this would only improve impressiveness by 1.1*16.25% = 17.9%, resulting in a score of 88 or "very impressive"

If we were to increase the original room's space by 10 units instead, '''S'''<sub>m</sub> becomes 0.28 (0.08 increase). Increasing the bottleneck stat results in a change of 0.08*51.25% = 4.1%, or 74 total impressiveness or "somewhat impressive"
</div></div>

=== Wealth ===
This is the sum of the [[Market Value]] of all items in the room and all walls and doors surrounding the room. Walls, doors, columns and animal flaps in the outer corner count as well. The value of [[power conduit]]s in walls ''is'' also included, however, for some reason building or deconstructing a conduit doesn't immediately update room wealth. Only if wealth is recalculated for some other reason, is the value of the conduits included. The same is true when building a column in the outer corner of the wall.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < 500
| impoverished
|-
| >= 500 and < 700
| somewhat poor
|-
| >= 700 and < 2000
| mediocre
|-
| >= 2000 and < 4000
| somewhat rich
|-
| >= 4000 and < 10000
| rich
|-
| >= 10000 and < 40000
| luxurious
|-
| >= 40000 and < 100000
| very luxurious
|-
| >= 100000 and < 1000000
| extremely luxurious
|-
| >= 1000000
| unbelievably luxurious
|}

=== Beauty ===
This is the average environmental beauty of the room including its walls and doors with a penalty for small rooms. Walls, doors and columns in the outer corner count as well. Building or deconstructing a column in the outer corner doesn't trigger a recalculation however. Floor tiles underneath walls and doors have no influence.

Room beauty is calculated as:

<pre>TotalBeauty = sum(beauty for each internal cell) + sum(beauty for each adjacent cell)
WeightedSize = size if (size > 40) else (20 + size / 2)
RoomBeauty = TotalBeauty / WeightedSize</pre>

This means that all rooms with less than 40 internal space will have their beauty penalised.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
|-
| < -3.5
| hideous
|-
| >= -3.5 and < 0
| ugly
|-
| >= 0 and < 2.4
| neutral
|-
| >= 2.4 and < 5
| pretty
|-
| >= 5 and < 15
| beautiful
|-
| >= 15 and < 50
| very beautiful
|-
| >= 50 and < 100
| extremely beautiful
|-
| >= 100
| unbelievably beautiful

|}

=== Space ===
Indicates how much free space is available in the room. A room's Space score is 1.4 times the number of tiles in the room. Objects that prevent a pawn from standing in a space will decrease the available space in the room by 0.9 per tile the object covers. Thus, an occupied tile contributes a total of 0.5 to space. Objects that reduce space include beds, tables, workbenches, lamps, and heaters. Stools and chairs do not reduce space.

{| class="wikitable" style="margin-left: auto; margin-right: auto; border: none;"
! Value
! Description
! typical size*
|-
| < 12.5
| cramped
| 3x4 or smaller*
|-
| >= 12.5 and < 29
| rather tight
| 3x6, 4x5*
|-
| >= 29 and < 55
| average-sized
| 4x7, 5x6*
|-
| >= 55 and < 70
| somewhat spacious
|-
| >= 70 and < 130
| quite spacious
|-
| >= 130 and < 349.5
| very spacious
|-
| >= 349.5
| extremely spacious
|}
: (* These are "safe" approximations; as described, the items placed <u>in</u> the room can greatly reduce the effective size. For example, an empty 5x5 room has space (25 x 1.4 =) 35, easily "average" - when empty. However, placing just one bed (2 tiles), one table (2 tiles), a light, a heater, a plant pot and one artwork (1 tile each, a chair is "free") in that room reduces the effective space by -7.2 (= 8 tiles x .9), and the effective space is now 27.8, "rather tight".)

Note, that space of the room affects only its impressiveness. Careful to not confuse with Pawn's [[space]] need.

=== Cleanliness ===
This stat affects [[Surgery_Success_Chance_Factor#Room_Cleanliness_Multiplier|Surgery Success Chance]], [[Research#Research speed|research speed]], the chance that cooked meals will cause [[food poisoning]], and gene [[Assembly Speed Factor]].{{BiotechIcon}} A room's cleanliness is the average cleanliness score of all tiles in the room. It is determined by the type of [[floor]]ing, the presence of any [[filth]], and the cleanliness value of some furniture such as the [[butcher table]] and the [[stonecutter's table]]. Note that the type of [[floor]] under a door doesn't count for Cleanliness, but filth under a door does count.

<div style=display:inline-grid>
:::{| class="wikitable"
! Room Cleanliness
! Description
|-
| < -1.1
| very dirty
|-
| >= -1.1 and < -0.4
| dirty
|-
| >= -0.4 and < -0.05
| slightly dirty
|-
| >= -0.05 and < 0.4
| clean
|-
| >= 0.4
| sterile
|}
</div>
<div style=display:inline-grid>
:{| class="wikitable"
|-
! Surface
! Cleanliness<br/>Value
|-
|[[Void metal ]]{{AnomalyIcon}} || 1
|-
| [[Sterile tile]] floor || 0.6
|-
| [[Steel tile|Steel]], [[Silver tile|Silver]] or [[Gold tile|Gold]] floor || 0.2
|-
|[[Bioferrite plate]]{{AnomalyIcon}} || 0.2
|-
| all other constructed [[floor]]ing<nowiki>;</nowiki> [[Bridge]]s || 0
|-
| Natural stone ([[Rough stone|rough]] or [[Smooth stone|smoothed]]) || 0
|-
| [[Straw matting]] || -0.1
|-
| all other [[Environment#Terrain|natural surfaces]] (soil, gravel, etc.) || -1
|-
| [[Marsh]], [[Marshy soil]], [[Mud]], [[Broken asphalt]] || -2
|-
| [[Chunk]]s || -2
|-
|[[Flesh]]{{AnomalyIcon}} || -3
|-
| [[Filth|Dirt, rubble, all other filth]] || -5
|-
| [[Filth|Blood]] || -10
|-
| [[Filth|Insect blood, vomit, fuel puddle]] || -15
|-
| [[Filth|Corpsebile]] || -20
|}
</div>

Using "Toggle the beauty display" can help locate filth in a given room, which typically stands out due to its negative beauty.

== Map regions ==
Upon map generation, the map is divided into chunks of 12x12 squares called map regions. Each region requires a contiguous area and will be subdivided otherwise. Under no circumstance will a region extend beyond the initial 12x12 grid. Impassable buildings (both natural and artificial) are not considered as part of any map region for this purpose and will subdivide existing map regions accordingly. Regions will fuse when possible. Map regions are used for several calculations and can be seen in game via the debug option "Draw Regions".

<div class="mw-customtoggle-myDivision" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Some additional notes:</div>

<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-myDivision">
<div class="mw-collapsible-content" style="background:rgba(255,255,255,.5);margin-top:10px;padding:10px;border-radius:5px">
* Impassable buildings are never part of any map region.
** Impassable non-walls (ex: [[Ship engine]]) may create a "red" temporal map region on construction that will be removed once anything else is build/destroyed.
* Impassable terrain creates map regions confined to its extension.
** These regions don't interact with the regular ones, but otherwise follow the stated rules.
* Passable buildings, such as [[fence]]s and [[barricade]]s, create map regions along their extension.
** These "fence" regions won't interact with other kinds, but otherwise follow the stated rules.
* Doors have unique behavior
** Single tile doors create a 3 tile map region centered on the doors' tile, following the door's orientation, that overlaps with other map regions.
*** Impassable objects will delete the overlapping section, no interaction otherwise.
** Double tile doors create 2 map regions, 1 for each of its tiles.
** The map regions created by doors don't interact with any other, not even each other.
* The grid defining regions is drawn from the bottom-left of the map row by row.
</div></div>

== Version history ==
* [[Version/0.12.906|0.12.906]] - Added.
* 1.1 - Added room stats gizmo, which displays the stats of the room containing a selected building, at a glance.
* [[Royalty DLC]] release - Throne room role added.
* [[Ideology DLC]] release - Temple room role added.
* [[Version/1.3.3072|1.3.3072]] - Fix: Checking all beds instead of just humanlike ones for room owner.
* [[Version/1.4.3523|1.4.3523]] - Added the storeroom role for rooms with lots of shelves.
* [[Biotech DLC]] release - Nursery, playroom, classroom, and deathrest chamber roles added.
* [[Anomaly DLC]] release - Containment cell and ceremonial chamber roles added.
* [[Version/1.6.4518|1.6.4518]] - Some production buildings now have a work speed penalty if they are not in the correct room.

== Notes ==
{{Reflist}}

[[Category:Game mechanics]]

Immunity Gain Speed

2026-01-25T19:45:56Z

Aelanna: Neither "gradual" nor "rapid" are appropriate descriptors.

{{Stub|reason= order of operations. also add Medical Specialist Immunity Drive ability}}{{Stat
| default base value = 1.0
| to string style = PercentZero
| description = The speed at which this character gains immunity to [[disease]]s. If this is too slow, the character will [[Death|die]] from the disease before developing immunity.
| category = BasicsPawn
}} The value shown in-game is rounded to the nearest whole percent, while exact value is used in calculations.

While this stat can be seen in-game, the '''actual immunity gain speed''', measured in percentage per [[Time|day]], is hidden but can be deduced from thorough observations. It is calculated as a product of:
* Base immunity gain speed for the particular disease. For example, 23.88% per day for [[Flu#Humans|human Flu]].
* InfectionLuck, a pseudorandom factor ranging from 80% (Bad luck) to 120% (Good luck). It is set independently for each disease instance (when multiple pawns are affected by a disease outbreak, each of them gets their own disease instance). Wound infections in different organs of the same pawn are different instances, but only InfectionLuck of the oldest active infection comes into play (and only one infection immunity develops in organism, opposing all infection instances).
: ''Technical details. InfectionLuck is not stored in save file. Instead, it is calculated as a pseudorandom value depending on the world's seed (seedString) and disease's hediff ID (loadID). For example, it is ≈81.7511% for seed "InfectionLuck" and ID of 1947.''
* Immunity Gain Speed stat.

Immunity gain speed is '''not''' affected by medical tend quality.

==Stat factors==
Immunity Gain Speed stat is determined by many factors multiplicatively.

===Capacities===
[[Blood Filtration]]: [[Blood Filtration Importance::0.5|50%]] importance. No allowed defect. [[Blood Filtration Limit::-|No]] Max. So,
: {{math|Blood filtration factor {{=}} Blood Filtration ÷ 2 + 50%}}
Notable facts:
* [[Malaria]] progressively reduces Blood Filtration.
* A missing [[Kidney]] reduces Blood Filtration by 50%. This alone results in a Blood filtration factor of 75%.
* [[Cancer]] progressively reduces efficiency in the body part affected, potentially reducing Blood Filtration if it is in the Kidneys or [[Liver]].
* [[Luciferium]] adds 70% to Blood Filtration. This alone results in a Blood filtration factor of 135%.
* [[Detoxifier kidney]]s each add 5% Blood Filtration each compared to a healthy kidney. This alone results in a blood filtration factor of 102.5% (105% with two).
** This is mutually exclusive with [[Immunoenhancer]]s

===Saturation===
[[Saturation|Hunger/Food]]:
* 100%: Fed or Hungry
* 90%: Urgently Hungry (corresponds to Ravenously Hungry)
* 70%: Starving (corresponds to Malnourished)

===Rest===
[[Rest]] need:
* 100%: Rested
* 96%: Tired (corresponds to [[Thoughts#Exhaustion|Drowsy]] thought)
* 92%: Very tired (corresponds to [[Thoughts#Exhaustion|Tired]] thought)
* 80%: Exhausted (corresponds to [[Thoughts#Exhaustion|Exhausted]] thought)

In Bed:{{Check Tag|Crib?}}
* 95%: When resting/sleeping in an [[ancient bed]] {{IdeologyIcon}}.
* 100%: When not resting/sleeping or when resting/sleeping on the floor, ground or ([[animal sleeping spot|animal]] / [[double sleeping spot|double]] / [[baby sleeping spot|baby]] {{BiotechIcon}}) [[sleeping spot]].
* 105%: When resting/sleeping in a ([[double bedroll|double]]) [[bedroll]] or [[animal sleeping box]].
* 107%: When resting/sleeping in an [[animal bed]], ([[double bed|double]]) [[bed]], [[royal bed]], ([[slab double bed|double]]) [[slab bed]] {{IdeologyIcon}} or [[deathrest casket]] {{BiotechIcon}}.
* 111%: When resting/sleeping in a [[hospital bed]].
* 113%: When resting/sleeping in a hospital bed with attached [[vitals monitor]].
''Note that quality of the bed only influences the [[Rest Effectiveness|rest effectiveness]], not the immunity gain speed.''

Resting:
* 100%: Not resting. Also, when [[downed]], despite visually lying.
* 110%: Resting, sleeping or [[Recreation#Activities_table|skygazing]] (cloudwatching, stargazing, etc).

=== Age ===
{{Stub|section=1|reason=Verify the effect of things that affect life span, such as the [[Mild cell instability|cell instability]] gene, then provide examples for the resulting lifespans in the Age/IGS table - if verified, also verify on [[Disease]]}}
Generally, the multiplier for age follows a curve defined by 5 points.
{| class="wikitable"
|-
! Age !! Multiplier
|-
| 0.65 * Life Expectancy || 100%
|-
| 0.80 * Life Expectancy || 95%
|-
| 1.00 * Life Expectancy || 90%
|-
| 1.20 * Life Expectancy || 80%
|-
| 1.50 * Life Expectancy || 50%
|}

As the life expectancy for [[Human]]s is 80, the following are approximate values for them:
{| class="wikitable"
|-
! Age !! Immunity Gain Speed
|-
| <54 || 100%
|-
| 54 || 99%
|-
| 56 || 98%
|-
| 59 || 97%
|-
| 61 || 96%
|-
| 63 || 95%
|-
| 66 || 94%
|-
| 69 || 93%
|-
| 72 || 92%
|-
| 76 || 91%
|-
| 79 || 90%
|-
| 81 || 89%
|-
| 83 || 88%
|-
| 85 || 87%
|-
| 86 || 86%
|-
| 88 || 85%
|-
| 89 || 84%
|-
| 91 || 83%
|-
| 93 || 82%
|-
| 94 || 81%
|-
| 96 || 80%
|-
| 97 || 79%
|-
| 98 || 78%
|-
| 99 || 76%
|-
| 100 || 75%
|-
|}
After age 100, immunity linearly decreases to 50% at age 120 and remains there.

=== Misc ===
* [[Immunoenhancer]] {{RoyaltyIcon}}: {{+|8%}} per, {{+|16%}} max
** This is mutually exclusive with [[Detoxifier kidney]]s {{BiotechIcon}}
* [[Super-immune]] trait: {{+|30%}}
* [[Moral guide]]'s Preach Health ability {{IdeologyIcon}}: {{+|25%}}
* [[Strong immunity]] gene {{BiotechIcon}}: {{Good|x110%}}
* [[Super immunity]] gene {{BiotechIcon}}: {{Good|x150%}}
* [[Perfect immunity]] gene {{BiotechIcon}}: No effect, prevents most common disease but does not cure existing disease
* [[Weak immunity]] gene {{BiotechIcon}}: {{Bad|x90%}}
* [[Inbred]] gene {{BiotechIcon}}: {{Bad|x85%}}
* [[Mild cell instability]] gene {{BiotechIcon}}: {{Bad|x96%}}, Lifespan factor {{Bad|x80%}}, {{Bad|x300%}} [[Cancer]] rate
* [[Major cell instability]] gene {{BiotechIcon}}: {{Bad|x92%}}, Lifespan factor {{Bad|x60%}}, {{Bad|x500%}} Cancer rate

== Version history ==
* [[Version/0.12.906|0.12.906]] - Now affected by [[room stats]]

{{nav|stats|wide}}

Environment

2026-01-12T02:02:12Z

Aelanna: Removed previous addition as there appears to be no evidence in the code to support this claim and a quick test in a pure vanilla game shows no such mechanic: https://i.imgur.com/ZxcnIQ7.png

{| align=center
| {{Gameplay_Nav}}
|}
----


{{Stub|reason= Missing new Odyssey terrain and weather mechanics}}
{{TOCright}}

The map '''environment''' are all aspects of the map that often can not be directly influenced by the player, such as terrain, weather conditions and lighting.

== Beauty ==
{{Main|Beauty}}
Terrain, flooring, objects, and plants attribute to a tile's beauty, which in turn can affect a colonist's mood.
The contents of a tile have a cumulative effect on its beauty; i.e. a granite chunk (beauty of -10) on a carpeted floor (beauty of +2) gives the tile a net beauty of -8.
Certain unsightly objects, i.e. vomit, have one value when under a roof and a lower value when unroofed. This simulates the general disgust of seeing eyesores indoors versus encountering them outside.

== Space ==
Environment space (as opposed to the [[Space|Need for Space]]) is the count of how much space there is to freely move around in a room. This is all the floor tiles that are either empty or have objects that can be passed through at full speed, such as chairs, building materials, and the various "spots". All objects that either slow down or prevent movement through are not counted towards Environment Space. The "Space" number shown in the Environment display is this count x 1.4. This number is a measure of the entire room, and does not change depending on where a pawn is standing.

== Flora ==
{{Main|Plants}}
Certain plants and trees have beauty, and may also provide [[cover]] to colonists.

== Light ==
{{Stub|section=1|reason=1) Relationship between light % and plant growth speed e.g. Tinctoria grows so slow in normal soil under torch light that it rots before it grows enough to harvest 2) Effects of [[Dark vision]] and [[Ideoligion#Lighting|Lighting:Darkness preferred]] on mentioned stat and mood penalties}}
{{For|the furniture item|standing lamp}}

Light can be generated artificially or naturally. Artificial light is produced by appliances in a limited range. Natural light is generated throughout the map on unroofed tiles. Roofed tiles will be dark unless lit artificially.

Occasionally an [[Events#Eclipse|eclipse]] befalls the planet. Natural daytime light is no longer generated until it ends.

Light's importance lies in the following effects:
* Plant growth - Most plants have light requirements to grow.
:* 0% only: {{DLC Icons|Nutrifungus}}
:* 0%+: {{#Ask: [[Min Grow Light::0]] [[Name::!Nutrifungus]]| format = template | template = DLC Icons | link = none | sort = From DLC, Name | sep = , }}
:* 30%+: {{#Ask: [[Min Grow Light::0.3]]| format = template | template = DLC Icons | link = none | sort = From DLC, Name | sep = , }}
:* 51%+: ''All other plants''
* Power - Solar generators only produce power when naturally lit.
* Colonists want 30% light or better. This affects:
:* Colonists' mood - Colonists in sustained darkness will have the [[Thoughts list#In darkness|'In darkness']] thought. Sleeping colonists will not have this thought. Therefore, lighting is not needed in areas only used for sleeping.
:* Colonists' movement speed - Colonists in darkness will have a reduced [[move speed]], scaling to 80% at a light level of 0%. Due to this, combat at night or under unlit roofed areas can lead to a disadvantage against non-human opponents, such as insects, manhunter animals, or mechanoids. Pawns that are [[Sight|Blind]], have the [[Ideoligion#Lighting|Lighting: Darklight preferred]] precept,{{IdeologyIcon}} or have the [[Dark vision]] gene{{BiotechIcon}} are unaffected by this factor.
:* Colonists' global work speed - Similarly to their movement speed, colonists will have a work speed penalty when working in darkness, scaling to 80% at a light level of 0%. Pawns that are [[Sight|Blind]], have the [[Ideoligion#Lighting|Lighting: Darklight preferred]] precept,{{IdeologyIcon}} or have the [[Dark vision]] gene{{BiotechIcon}} are unaffected by this factor.
* [[Surgery success chance factor]] is optimized at 50% light or better.

There are three light levels: ''Dark'' (0-29%), ''Lit'' (30-89%), and ''Brightly lit'' (90-100%). Each tile on the map has one of these light levels. The light level of a tile is listed in the tile's information area located above the Architect menu (when the menu is minimized). The light level is immediately followed by the brightness given in a percentage (%).

{| class="wikitable" style = "text-align:center; border-width=10;" width="260"
| colspan = 4 | '''Light levels according to Light (%)'''
|-
| style = "text-align:left;" | Light (%)
| style="background-color:#B8C0B8" | 0-29
| style="background-color:#FFFFF0" | 30-89
| style="background-color:#FFFFD8" | 90-100
|-
| style = "text-align:left;" | Light level
| style="background-color:#B8C0B8" | Dark
| style="background-color:#FFFFF0" | Lit
| style="background-color:#FFFFD8" | Brightly lit
|}

=== Darklight ===
{{Ideology|section=1}}
{{Stub|section=1|reason=General also two way links}}

Based on a specific colour.
It pleases [[ideoligion]]s with the [[Ideoligion#Lighting|Lighting: Darklights Preferred]] precept, giving those with the precept a {{Thought| desc=This dim light is perfect. I feel focused and energized.| label=darklight| value=+4| stack=1}},

* [[Darktorch]]
* [[Fungus darktorch]]
* [[Standing lamp]] (configured correctly)
* [[Darklight brazier]]{{RoyaltyIcon}}

=== Artificial light sources ===
Light in roofed areas is provided by the following appliances:

<div><li style="display: inline-table;">
{| {{STDT| sortable c_11 text-center}}
! Name !! <abbr title="The furthest away a tile can be before it falls below 30% light">Light Radius</abbr>
|-
{{#ask: [[Light Radius::+]]
| format = template
| template = Ask Table Formatter
| ?Light Radius
| sort = From DLC, Name
| link = none
}}
|}
</li><div>

=== Daylight timing and latitude ===
Daylight, or natural light, is the light generated on unroofed tiles throughout the map. The timing and strength of daylight is affected by latitude, time of year, and time of day, due to the planet's apparent axial tilt.

This effect is more pronounced at extreme northern and southern latitudes, which can result in light levels not reaching 0% at night or 100% at daytime.

Near the central latitude, light level change throughout the day as follows:
{| class = "wikitable" width="180"
! Start time
! Light level
|- style="background-color:#FFFFF0"
| 4h || Lit
|- style="background-color:#FFFFD8"
| 7h || Brightly lit
|- style="background-color:#FFFFF0"
| 17h || Lit
|- style="background-color:#B8C0B8"
| 20h || Dark
|}

==== Day Length Table ====
Note that the below values represent the number of hours that the light level is above 30%, meaning there is no guarantee that it will reach 100%.
{| class="wikitable"
|-
! Latitude !! Aprimay 1 !! Aprimay 6 !! Aprimay 11 !! Jugust 1 !! Jugust 6 !! Jugust 11 !! Septober 1 !! Septober 6 !! Septober 11 !! Decembary 1 !! Decembary 6 !! Decembary 11
|-
| '''90° N''' || 0 || 0 || 0 || 24 || 24 || 24 || 24 || 24 || 24 || 0 || 0 || 0
|-
| '''75° N''' || 0 || 0 || 0 || 10.7 || 24 || 24 || 24 || 24 || 24 || 0 || 0 || 0
|-
| '''60° N''' || 11.2 || 11.7 || 12.8 || 14.1 || 15.5 || 16.5 || 16.8 || 16.2 || 15.0 || 13.6 || 12.3 || 11.4
|-
| '''45° N''' || 12.6 || 12.9 || 13.5 || 14.3 || 15.1 || 15.6 || 15.8 || 15.5 || 14.8 || 13.9 || 13.2 || 12.7
|-
| '''30° N''' || 13.5 || 13.7 || 14.0 || 14.5 || 14.9 || 15.3 || 15.4 || 15.2 || 14.8 || 14.3 || 13.9 || 13.6
|-
| '''15° N''' || 14.3 || 14.4 || 14.5 || 14.8 || 15.0 || 15.2 || 15.2 || 15.1 || 14.9 || 14.7 || 14.5 || 14.4
|-
| '''0°''' || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2 || 15.2
|-
| '''15° S''' || 15.2 || 15.1 || 14.9 || 14.7 || 14.5 || 14.4 || 14.3 || 14.4 || 14.5 || 14.8 || 15.0 || 15.2
|-
| '''30° S''' || 15.4 || 15.2 || 14.8 || 14.3 || 13.9 || 13.6 || 13.5 || 13.7 || 14.0 || 14.5 || 14.9 || 15.3
|-
| '''45° S''' || 15.8 || 15.5 || 14.8 || 13.9 || 13.2 || 12.7 || 12.6 || 12.9 || 13.5 || 14.3 || 15.1 || 15.6
|-
| '''60° S''' || 16.8 || 16.2 || 15.0 || 13.6 || 12.3 || 11.4 || 11.2 || 11.7 || 12.8 || 14.1 || 15.5 || 16.5
|-
| '''75° S''' || 24 || 24 || 18.7 || 15.0 || 12.2 || 10.4 || 9.9 || 11.0 || 13.2 || 16.4 || 20.6 || 24
|-
| '''90° S''' || 24 || 24 || 24 || 24 || 24 || 0 || 0 || 0 || 24 || 24 || 24 || 24
|}

==== Plant growth time table ====
{| class="wikitable"
|-
! Latitude !! Aprimay 1 !! Aprimay 6 !! Aprimay 11 !! Jugust 1 !! Jugust 6 !! Jugust 11 !! Septober 1 !! Septober 6 !! Septober 11 !! Decembary 1 !! Decembary 6 !! Decembary 11
|-
| '''90° N''' || 0 || 0 || 0 || 0 || 24 || 24 || 24 || 24 || 24 || 0 || 0 || 0
|-
| '''75° N''' || 0 || 0 || 0 || 5.8 || 24 || 24 || 24 || 24 || 18.6 || 0 || 0 || 0
|-
| '''60° N''' || 8.9 || 9.4 || 10.5 || 11.9 || 13.2 || 14.0 || 14.3 || 13.8 || 12.7 || 11.3 || 10.0 || 9.1
|-
| '''45° N''' || 11.0 || 11.3 || 11.9 || 12.7 || 13.4 || 13.9 || 14.1 || 13.8 || 13.1 || 12.4 || 11.6 || 11.1
|-
| '''30° N''' || 12.2 || 12.4 || 12.7 || 13.2 || 13.6 || 13.9 || 14.0 || 13.8 || 13.4 || 13.0 || 12.6 || 12.3
|-
| '''15° N''' || 13.2 || 13.2 || 13.4 || 13.6 || 13.8 || 14.0 || 14.0 || 13.9 || 13.7 || 13.5 || 13.3 || 13.2
|-
| '''0°''' || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1 || 14.1
|-
| '''15° S''' || 14.0 || 13.9 || 13.7 || 13.5 || 13.3 || 13.2 || 13.2 || 13.2 || 13.4 || 13.6 || 13.8 || 14.0
|-
| '''30° S''' || 14.0 || 13.8 || 13.4 || 13.0 || 12.6 || 12.3 || 12.2 || 12.4 || 12.7 || 13.2 || 13.6 || 13.9
|-
| '''45° S''' || 14.1 || 13.8 || 13.1 || 12.4 || 11.6 || 11.1 || 11.0 || 11.3 || 11.9 || 12.7 || 13.4 || 13.9
|-
| '''60° S''' || 14.3 || 13.8 || 12.7 || 11.3 || 10.0 || 9.1 || 8.9 || 9.4 || 10.5 || 11.9 || 13.2 || 14.0
|-
| '''75° S''' || 17.3 || 16.0 || 13.6 || 10.6 || 7.6 || 5.1 || 4.3 || 6.0 || 8.8 || 11.8 || 14.6 || 16.7
|-
| '''90° S''' || 24 || 24 || 24 || 0 || 0 || 0 || 0 || 0 || 0 || 0 || 24 || 24
|}

==== Daylight math details ====
{{rwbox
| nocat=true
| type = warning
| text = <span style="color:#FF3333";>'''Warning!''' Trigonometry ahead!</span>'''<br>This section gets into complicated mathematical detail. Proceed at own risk
}}
The calculation of sunlight is surprisingly involved. On a nutshell: the formula obtains the angle between the vectors Latitude and Sun Position, subtracts an angle θ from it (determined by Latitude), obtains the cosine of the difference, and divides this number by 0.7. Finally, this result is capped between 0 (no light) and 100% (full light).

If you only care about the final formula, go to "Final formula" below. Otherwise, carry on.

The amount of sunlight a given cell receives depends on its Latitude, Day of the year, and Hour of the day. The simplified steps to reach the final value are:

:1. Obtain the factor "u" for the given latitude
::{| class="wikitable"
|-
! Latitude !! Value of u
|-
| <= 70 || 0.2
|-
| [70, 75] || Latitude * 13/50-18
|-
| =>75|| 1.5
|}

:2. Obtain Sun Position Vector SP = <code>{SPx, SPy, SPz}</code>. Do note these formulas are not in degrees, but radians.
:* SPx = -cos(Hour * π / 12)
:* SPy = -cos(π * Day/30) * u
:* SPz = -sin(Hour * π / 12) [NOT ACTUALLY USED, BUT PART OF THE VECTOR]

:3. Calculate angle θ. Do note that the values of this table are in degrees. To convert to radians, multiply result by π / 180
::{| class="wikitable"
|-
! Latitud !! Value of θ
|-
| <= -60 || 19
|-
| [-60, 60] || 36 - abs(x) * 17/60 
|-
| [60, 70] || 19
|-
| [70, 75] || 299 - 4x
|-
| >75 || -1
|}

:4. Calculate the angle (Δ) between the vector Latitude (L) y SP.
:* Δ = arc cos [ ( cos(Latitude) * SPx + sen(Latitude) * SPy ) / <span style="white-space: nowrap">√<span style="text-decoration:overline;"> 1 + SPy<sup>2</sup> </span></span> ] 

:5. '''Sunlight''' = cos(Δ - θ)/0.7; Capped between 0 and 1 (100%).

Do note that the creation of the vector Latitude : <code>{cos(''latitude''), sin(''latitude''), 0}</code> was omitted for simplicity.

<div class="mw-customtoggle-MathDetails" style="display:inline-block;background:rgba(128,128,128,0.5);color:white;padding:5px;border-radius:5px;outline:none;user-select:none">Final Formula:</div>

<div id="mw-customcollapsible-MathDetails" class="mw-collapsible mw-collapsed">

[[File:Sunlight formula 5.png|600px]]



Where:
<div style=display:inline-grid>
:{| class="wikitable"
|-
! Latitude !! Value of u
|-
| <= 70 || 0.2
|-
| [70, 75] || Latitude * 13/50-18
|-
| =>75 || 1.5
|}
</div>
<div style=display:inline-grid>
:{| class="wikitable"
|-
! Latitud !! Value of θ
|-
| <= -60 || 19
|-
| [-60, 60] || 36 - abs(x) * 17/60 
|-
| [60, 70] || 19
|-
| [70, 75] || 299-4x
|-
| >75 || -1
|}
</div>

</div></div>

Interestingly, while some effects are applied differently above latitude <code>70</code> (70° N), these do not seem to apply below <code>-70</code> (70° S). This has some odd effects on extreme Latitudes, such as the south pole having neither full darkness nor full light.

Getting useful data from this formula is inconvenient. You can use [https://docs.google.com/spreadsheets/d/1dI8CoR9OMk679Gyvr8lXrKUNtfNdCQPp/edit?usp=sharing&ouid=114344865191558455918&rtpof=true&sd=true this google doc] to get a better idea of how many hours of daylight a given tile (based on Latitude) will have through the year.




== Openness ==
{{stub|section=1|reason=Large enough enclosed spaces seem to blur these boundaries}}
Openness refers to the often critical aspect of structures being open to the outside. It affects many things such as temperature, item deterioration, light, exposure to weather, and certain events.

Every tile on the map falls into one of three categories:
* Outdoors - not enclosed by any structure, even if there is a roof.
* Indoors - completely enclosed structure, completely roofed.
* Unroofed - completely enclosed structure, but with one or more unroofed tiles.

Sufficiently large unroofed rooms, approximately 300 tiles, are considered outdoors.{{Check Tag|Detail Needed}}

== Temperature ==
{{Main|Temperature}}
Environmental temperature is affected outdoors mainly by the map's biome and by the current season. Temperature affects a plant's ability to grow. Temperature affects a human's comfort, and health in extreme temperatures.

== Terrain ==
Terrain consists of the map's walking surface, terrain features, and mountain areas. Terrain affects things including walking speed, where plants can grow, and may prohibit construction.

'''Natural surface terrain''' includes soil, rich soil, marshy soil, marsh, mud, sand, lichen-covered dirt, gravel, rough stone (granite, marble, etc.), rough-hewn stone, shallow water, and deep water.

'''Terrain features''' include steam geysers and mountains. The steam from a geyser produces heat and an enclosed area around it will heat up unless unroofed. A mountain cannot be destroyed, even if all of its stone and ore has been mined out. What remains are terrain tiles listed as 'overhead mountain'.

=== Naturally generated surfaces ===
{{stub|section=1|reason=Anomaly terrains - Flesh and Gray surface, odyssey terrains}}
{{Split|section=1|reason=Individual pages for each terrain. Then make and distribute nav template}}
{{Recode|section=1|reason=Automate table once all pages created}}
{{For|the artificial flooring|Floors#Comparison table{{!}}Floors}}
While most terrain properties are self-explanatory, some require special attention.
* '''Path cost''' determines how difficult is to travers a given terrain.
* '''Move Speed Modifier''' is the net effect of said cost, and is obtained with the formula <code>13/(13 + Path cost)</code> rounded.
* '''Terrain Support''' determines what kind of structures can be build on a given terrain. If a given structure has a '''Terrain Affordance''' not listed for a given terrain, then said terrain is not a valid construction site. The types used are:
**'''Light''': Supports light structure.<br/>
**'''Medium''': Supports medium structures.<br/>
**'''Heavy''': Supports heavy structures.<br/>
**'''ShallowWater''': Can be built on with things that are waterproof.<br/>
**'''MovingFluid''' (moving water): Contains power usable for hydroelectrics.<br/>
**'''Bridgeable''': [[Bridge]] can be built over this terrain.<br/>
**'''GrowSoil''' (growable): Things can grow here. Unsure if is does anything or if merely indicative.<br/>
**'''Diggable''': Able to build [[grave]]s.<br/>
**'''SmoothableStone''' (smoothable): Can be ground and smoothed into smooth stone.<br/>
*'''Filth Mask''' determines what kind of [[filth]] can be applied on this terrain. Most natural floors only accept '''Unnatural''' filth, if any at all, but there are exceptions.
*'''Tag''' use is unclear. It may be used on map generation.

As of [[Version/1.5.4104]], all terrains with Heavy '''Terrain Support''' also support both Medium and Light. To help the readability of this table, only the '''Heavy''' tag will be used in those cases.

{| {{STDT| sortable c_25 text-center mw-collapsible}}
! Type !! Move Speed <br/>Modifier !! [[Plants#Fertility|Fertility]] !! Terrain<br/>Support !! [[Bridge]]able !! [[Grave|Diggable]] !! Terrain<br/>Type !! Beauty<br>Indoors/<br/>Outdoors !! [[Cleanliness]] !! Filth<br/>mask{{ref label|Fmask|1}} !! Dries<br/> To{{ref label|DriesTo|2}} !! Tags !! [[Path cost|Path<br/>cost]] !! [[Filth#Generation|Generates<br/>Filth]] !! Allows<br/>Special<br/>Attack{{ref label|ASA|3}} !! Others
|- id="Broken asphalt"
! [[Broken asphalt]]
| 100% || 0% || Heavy || {{Cross}} || {{Cross}} || - || -1 || -2 || {{Check}} || - || Road || 0 || {{Cross}} || {{Cross}} || 0{{Icon Small|silver}}. Removable
|- id="Packed dirt"
! [[Packed dirt]]
| 93% || 0% || Heavy || {{Cross}} || {{Check}} || Soil || -1 || -1 || {{Check}} || - || Road || 1 || [[Filth#Dirt|Dirt]] || {{Cross}} ||

|- id="Chest-deep moving water"
! [[Chest-deep moving water]]
| 24% || 0% || - || {{Check}} || {{Cross}} || - || 0 || 0 || {{Cross}} || - || Water{{ref label|water|4|1}} || 42 || {{Cross}} || [[Hediffs#Water|Water]] || Extinguishes Fire<br/>Traversing generates thought [[Mood#Soaking wet|Soaking wet]]
|- id="Deep ocean water"
! [[Deep ocean water]]
| 0% || 0% || - || {{Cross}} || {{Cross}} || - || 0 || 0 || {{Cross}} || - || Water{{ref label|water|4|2}}<br/> ocean || 300{{ref label|Impassable|5|1}} || {{Cross}} || [[Hediffs#Water|Water]] || Impassable<br/>Extinguishes Fire
|- id="Deep water"
! [[Deep water]]
| 0% || 0% || - || {{Cross}} || {{Cross}} || - || 0 || 0 || {{Cross}} || - || Water{{ref label|water|4|3}} || 300{{ref label|Impassable|5|2}} || {{Cross}} || [[Hediffs#Water|Water]] || Impassable<br/>Extinguishes Fire

|- id="Shallow ocean water"
! [[Shallow ocean water]]
| 30% || 0% || ShallowWater || {{Check}} || {{Cross}} || - || 0 || 0 || {{Cross}} || [[#Gravel|Stony soil]] || Water{{ref label|water|4|4}}<br/> ocean || 30 || {{Cross}} || [[Hediffs#Water|Water]] || Extinguishes Fire<br/>Traversing generates thought [[Mood#Soaking wet|Soaking wet]]
|- id="Shallow moving water"
! [[Shallow moving water]]
| 30% || 0% || ShallowWater<br/> MovingFluid || {{Check}} || {{Cross}} || - || 0 || 0 || {{Cross}} || - || Water{{ref label|water|4|5}}<br/> River || 30 || {{Cross}} || [[Hediffs#Water|Water]] || Extinguishes Fire<br/>Traversing generates thought [[Mood#Soaking wet|Soaking wet]]
|- id="Shallow water"
! [[Shallow water]]
| 30% || 0% || ShallowWater || {{Check}} || {{Cross}} || - || 0 || 0 || {{Cross}} || [[#Gravel|Stony soil]] || Water{{ref label|water|4|6}} || 30 || {{Cross}} || [[Hediffs#Water|Water]] || Extinguishes Fire<br/>Traversing generates thought [[Mood#Soaking wet|Soaking wet]]
|- id="Marsh"
! [[Marsh]]
| 30% || 0% || ShallowWater || {{Check}} || {{Cross}} || - || -3/0 || -2 || {{Cross}} || [[#Soil|Soil]] || - || 30 || [[Filth#Dirt|Dirt]] || [[Hediffs#Mud|Mud]] || Extinguishes Fire<br/>Traversing generates thought [[Mood#Soaking wet|Soaking wet]]

|- id="Soil"
! [[Soil]]
| 87% || 100% || Heavy<br/> GrowSoil || {{Cross}} || {{Check}} || Soil || -3/0 || -1 || {{Check}} || - || Soil || 2 || [[Filth#Dirt|Dirt]] || [[Hediffs#Dirt|Dirt]] ||
|- id="Lichen-covered soil"
! [[Lichen-covered soil]]
| 81% || 100% || Heavy<br/> GrowSoil || {{Cross}} || {{Check}} || Soil || -3/0 || -1 || {{Check}} || - || Soil || 3 || [[Filth#Dirt|Dirt]] || [[Hediffs#Dirt|Dirt]] ||
|- id="Marshy soil"
! [[Marshy soil]]
| 48% || 100% || Light<br/> GrowSoil || {{Check}} || {{Check}} || Soil || -3/0 || -2 || {{Check}} || [[#Soil|Soil]] || Soil || 14 || [[Filth#Dirt|Dirt]] || [[Hediffs#Dirt|Dirt]] ||
|- id="Rich soil"
! [[Rich soil]]
| 87% || 140% || Heavy<br/> GrowSoil || {{Check}} || {{Check}} || Soil || -3/0 || -1 || {{Check}} || [[#Soil|Soil]] || Soil || 2 || [[Filth#Dirt|Dirt]] || [[Hediffs#Dirt|Dirt]] ||

|- id="Stony soil"
! [[Stony soil]]
| 87% || 70% || Heavy<br/> GrowSoil || {{Check}} || {{Check}} || - || -3/0 || -1 || {{Check}} || - || Soil || 2 || [[Filth#Dirt|Dirt]] || [[Hediffs#Gravel|Gravel]] ||

|- id="Sand"
! [[Sand]]
| 76% || 10% || Heavy || {{Cross}} || {{Check}} || Sand || -3/0 || -1 || {{Check}} || - || Sand || 4 || [[Filth#Sand|Sand]] || [[Hediffs#Sand|Sand]] ||
|- id="Soft sand"
! [[Soft sand]]
| 48% || 0% || Light || {{Cross}} || {{Check}} || Sand || -3/0 || -1 || {{Check}} || [[#Sand|Sand]] || Sand || 14 || [[Filth#Sand|Sand]] || [[Hediffs#Sand|Sand]] ||

|- id="Mud"
! [[Mud]]
| 48% || 0% || - || {{Check}} || {{Cross}} || Soil || -3/0 || -2 || {{Check}} || [[#Soil|Soil]] || - || 14 || [[Filth#Dirt|Dirt]] || [[Hediffs#Mud|Mud]] ||
|- id="Ice"
! [[Ice]]
| 48% || 0% || Heavy || {{Cross}} || {{Check}} || - || -3/0 || 0 || {{Check}} || - || - || 14 || [[Filth#Dirt|Dirt]] || {{Cross}} || -

|- id="Polluted"
! [[Pollution|Polluted terrain]]{{BiotechIcon}}
| - || 0-50%{{ref label|Polluted_F|6}} || - || - || - || - || -1 || - || - || - || - || - || - || - || Overlay: Applies stats over existing terrain (additive)<br/>Overlay: Changes graphics of affected terrain.<br/>Can be removed.<br/>Allows growth of [[Toxipotato plant|Toxipotato]], [[Gray pine tree|Gray pine]], [[Pebble cactus]], [[Rat palm tree|Rat palm]]<br/>Prevents growth of most other plants.<br/>Colonist receive [[toxic buildup]] from waking here.
|- id="Rough stone"
! [[Rough stone]]
| {{%|{{Q|Rough stone|Move Speed Factor}} }} || 0% || Heavy || {{Cross}} || {{Cross}} || Stone || -1 || 0 || {{Check}}{{ref label|RStone|7}} || - || - || 2 || {{Cross}} || {{Cross}} || [[#Smooth stone|Smooothable]]<br/>Hardcoded{{ref label|Hardcode|8}}
|- id="Rough-hewn stone"
! [[Rough-hewn stone]]
| {{%|{{Q|Rough-hewn stone|Move Speed Factor}} }}|| 0% || Heavy || {{Cross}} || {{Cross}} || Stone || -1 || 0 || All || - || - || 1 || {{Cross}} || {{Cross}} || [[#Smooth stone|Smooothable]]<br/>Hardcoded{{ref label|Hardcode|8}}
|- id="Smooth stone"
! [[Smooth stone]]
| {{%|{{Q|Smooth stone|Move Speed Factor}} }}|| 0% || Heavy || {{Cross}} || {{Cross}} || Stone || 2 || 0 || All || - || - || 0 || {{Cross}} || {{Cross}} || 5{{Icon Small|silver}}.<br/>Natural, non-generated floor/terrain hybrid.<br/>Paintable<br/>Hardcoded{{ref label|Hardcode|8}}

|- id="Gray Surface"
! [[Gray surface]]{{AnomalyIcon}}
| 87% || 0% || Heavy || {{Cross}} || {{Cross}} || - || 0 || 0 || {{Check}}? || - || Floor || 2 || {{Cross}} || {{Cross}} || Only present on the Labyrinth.
|- id="Flesh Floor"
! [[Flesh]]{{AnomalyIcon}}
| 87% || 0% || Heavy || {{Cross}} || {{Check}} || - || -10/-5 || -3 || {{Check}}? || - || Floor || 2 || ? || {{Cross}} || Behaves like a natural Floor.<br/>Cleaning time Mult 150%<br/>Removable.<br/>Inflammable 32%
|}
:{{note label|Fmask|1}}The kind of Filth accepted by this terrain. {{Check}} denotes terrains that accept '''Unnatural''' filth, {{Cross}} those that accept none. Special cases are denoted as such.
:{{note label|DriesTo|2}}As Stony soil doesn't exist in [[Sea ice]] nor [[Ice sheet]], it dries to Ice instead.
:{{note label|ASA|3}}All of these attacks have a cooldown of 1.5 seconds, require the '''KickMaterialInEyes''' capacity, and apply a Hediff of the same name.
:4{{note label|water||1}}{{note label|water||2}}{{note label|water||3}}{{note label|water||4}}{{note label|water||5}}{{note label|water||6}} All water tiles triple the deterioration rate. Additionally, these have a perceived path cost of 180 if undrafted and of 18 when [[draft]]ed
:5{{note label|Impossible||1}}{{note label|Impossible||2}}Redundant due to being Impassable. It would result in a 4.2% '''Move Speed Modifier''' otherwise.
:{{note label|Polluted_F|6}}The fertility is capped at 50%, but will not affect the value of the original terrain if it was equal or lower than that.
:{{note label|RStone|7}}Plus any defined on NaturalTerrainBase. In vanilla, this in just '''Unnatural''' filth.
:{{note label|Hardcode|8}}Not on the xml files but rather defined programmatically for all stone types.

=== Steam geyser ===
{{stub|section=1|reason=Specific numbers on heat needed}}
[[File:Steam geyser.png|frameless|64px]] Steam geysers are terrain features that allow the placement of a [[geothermal generator]] on them and also output a significant amount of [[temperature|heat]] when sealed in a roofed room.

The steam geyser sprays after a random delay between {{Ticks|500}} and {{Ticks|2000}}. It will then spray for between {{Ticks|200}} and {{Ticks|500}}. While spraying, it will output 40 heat every {{ticks|20}}. Thus, it averages {{#expr: (60*40*((500+200)/2)/20)/((2000+500/2) + (200+500)/2) round 2}} heat per second, with no maximum temperature.

Besides their use in power generation, they can also be used to heat bases and greenhouses without the need for electricity or fuel by sealing them in. Like any means of [[temperature]] regulation, geysers require an enclosed and [[roof|roofed]] [[room]] to actually cause a change in heat. If you don't want heat, keep the geothermal room without a roof.

== Weather ==
{{stub|section=1|reason=Exact details of how large fires on the map cause rain needed. Rain details should be split from the rain weather type (because its not the only weather type that includes raining) and details discussed including short circuiting, increasing fuel consumption of torch, campfire and brazier variants, which weather types include rain, whether snow counts as rain for all mechanics etc, similarly Snow and its unique effects including [[Snow]] being merged into here. [[Odyssey DLC]] weathers need notes as they have additioonal effects, e.g. torrential rain causing flooding.}}

Weather events occur from time to time depending on the biome and time of year, with the current weather listed at the right edge of the screen. When a weather event ends the weather returns to Clear. Each weather event has a general effect on wind speed.

Wind speed continually varies between 0% to 150% but it is not displayed onscreen. Wind speed is a direct multiplier of a [[wind turbine]]'s nominal power output of {{Q|Wind turbine|Power Consumption #}}W. At 50% wind speed a wind turbine produces {{#expr:0.5*{{Q|Wind turbine|Power Consumption #}}}}W up to a maximum of {{#expr:1.5*{{Q|Wind turbine|Power Consumption #}}}}W at 150%. Note that the "max power output" listed in the infobox claims that {{Q|Wind turbine|Power Consumption #}}W is the maximum under "ideal conditions" - this is incorrect.

The [[Weather controller]]s {{RoyaltyIcon}} can force a single type of weather to constantly appear, and will only allow natural changes in weather once it is destroyed.
[[Fire#Rain event|Large fires]] can also influence the weather cycle, and can encourage rainy weather to arrive faster than it would otherwise for the duration of the fire.

{| class = "wikitable sortable"
|+ style = "text-align: left; font-size:120%;" | Weather types
|-
! Label
! Time of year
! Temperature range <ref>Can continue even if the temperature exits the appropriate range, once started.</ref>
! [[Weapons#Accuracy|Accuracy modifier]]
! Movement speed modifier
! Wind speed
! Wind speed modifier
! Can put out fires
! Snowing rate
! Notes
|-
| Clear
| Any
| Any
| 100%
| 100%
| None to Moderate
| 100%
| No
| None
|
|-
| Fog
| Any
|Any
| 50%
| 100%
| None to Calm
| 50%
| No
| None
| Suppresses firewatcher if forced {{RoyaltyIcon}}
|-
| Rain
| Any
| {{Temperature|0|100}}
| 80%
| 90%
| Calm to Moderate
| 80%
| Yes
| None
| Rain intensity can vary. Rain will put out any outdoor fires on the map. Rain can cause electronic objects to short circuit.
|-
| Dry Thunderstorm
| Any
| Any
| 100%
| 100%
| Moderate to Extreme
| 150%
| No
| None
| [[Lightning]] strikes from thunderstorms can ignite flammable objects, including flora. If accompanied by rain the fires should be extinguished without becoming a threat.
|-
| Rainy Thunderstorm
| Any
| Any
| 80%
| 80%
| Moderate to Extreme
| 150%
| Yes
| None
|
|-
| Foggy rain
| Any
| Any
| 50%
| 90%
| None to Calm
| 150%
| Yes
| None
|
|-
| Hard snow
| Mainly Winter
| {{Temperature|-270|-0.5}}
| 80%
| 80%
| None to Moderate
| 150%
| Yes
| 120%
| Weather event that can distribute [[Snow]] onto the terrain.
|-
| Soft snow
| Mainly Winter
| {{Temperature|-270|-0.5}}
| 80%
| 100%
| None to Moderate
| 150%
| Yes
| 80%
| Weather event that can distribute [[Snow]] onto the terrain.
|-
|[[Events#Flashstorm|Flashstorm]]
| Any
| Any
| 100%
| 100%
| None to moderate
| 100%
| No
| None
| An extreme version of the dry thunderstorm, and an event of its own (rather than normal weather changes). [[Lightning]] strike many times in a row in a small area, igniting anything flammable and causing giant wildfires which can spread to your base easily. It also disables rain for a short time.
|-
| Gray Pall{{AnomalyIcon}}
| Any
| Any
| 80%
| 100%
| None to Calm
| 50%
| No
| None
| Weather event that can occur occasionally after the [[Void monolith|Monolith]]{{AnomalyIcon}} has been activated. Colonists inside during gray pall will receive {{Thought| desc=It feels like the world is sick and dying.| label=Gray pall| value=-3| stack=1}} while pawns outside will receive {{Thought| desc=It feels like the world is sick and dying. The putrid air makes me want to vomit.| label=Gray pall exposure| value=-6| stack=1}}.
|-
| Windy{{OdysseyIcon}}
| Any
| Any
| 100%
| 90%
| 150-300%
| 150%
| No
| None
|
|-
| Tox rain{{OdysseyIcon}}
| Any
| {{Temperature|0|100}}
| 80%
| 90%
| None to Extreme
| 150%
| Yes
| None
| Creates Toxic Buildup on pawns exposed to rain, and -8 thought "Toxic Water". Does not kill plants like Toxic Fallout.
|-
| Sandstorm{{OdysseyIcon}}
| Any
| {{Temperature|10|100}}
| 80%
| 80%
| Moderate to Extreme
| 150%
| No
| None
| Shuttles can not launch during a sandstorm.
|-
| Blind fog{{OdysseyIcon}}
| Any
| Any
| 50%
| 100%
| None to Calm
| 50%
| No
| None
| Reduces maximum range of ALL weapons to 23, everywhere on the map, except for [[Unique weapons]] with the Aim Assistance trait. Also applies to many line-of-sight abilities like [[jump pack]]s and skip [[psycast]]s{{RoyaltyIcon}}. Shuttles can not launch during blind fog.
|-
| Overcast{{OdysseyIcon}}
| Any
| Any
| 100%
| 100%
| None to Moderate
| 100%
| No
| None
|
|-
| Blizzard{{OdysseyIcon}}
| Any
| {{Temperature|-270|-0.5}}
| 70%
| 70%
| Moderate to Extreme
| 150%
| Yes
| 150%
| Shuttles can not launch during blizzard.
|-
| Torrential rain{{OdysseyIcon}}
| Any
| {{Temperature|0|100}}
| 75%
| 80%
| None to Extreme
| 150%
| Yes
| None
| Weather event that causes flooding in already wet areas ie. rivers, marches, etc. flooding can be contained by placing walls or bridges along wet areas.
|}
<references/>

== Lightning ==
[[File:Dry Thunderstorm.png|400px|thumb|right|Lightning in a [[Environment#Weather|Dry thunderstorm]] ]]
'''Lightning''' is created either naturally through thunder and flashstorms, or artificially with the [[Flashstorm (psycast)|flashstorm]] psycast{{RoyaltyIcon}}. These do 10 [[Damage types#Flame|Flame]] damage in a 3x3 area (1.9 block radius) and start [[fire]]s to objects in the area of effect that are not under a roof. Dry thunderstorms can be especially dangerous, starting fires around the map without rain to put them out. The flashstorm psycast should be used with caution, preferably in areas without vegetation or during rain. Lightning can also be spawned in with a debug command in [[development mode]].

Lightning is bright enough to momentarily power [[solar generator]]s and grow [[plants]].

== Version history ==
* [[Version/0.0.245|0.0.245]] - Weather (rain/fog) now affects chances of hitting a target
* [[Version/0.3.410|0.3.410]] - Rain now slowly washes away [[Filth|blood]]. Added rich dirt patches.
* Beta 19/ 1.0 - Changed deep moving water to chest-deep moving water: walkable but slower than shallow water. Shallow water movement cost 12 -> 22. Sand fertility 6% -> 10%.
* [[Version/1.1.0|1.1.0]] - Fix: Wind turbines register no wind during windy storm.
* [[Version/1.4.3523|1.4.3523]] - Fix: Geysers have a deconstruct gizmo in god mode which causes and error when clicked.

[[Category:RimWorld game]]

Lung rot

2026-01-07T16:07:27Z

Aelanna: Verified incorrect, nothing other than the lung implants or Perfect Immunity makes a pawn immune to further lung rot infections.

{{Stub|reason=Treatment, causes, general. Numbers on MTB cases for severity would be very useful.}}
__NOTOC__
'''Lung rot''' is a long-lasting [[disease]] that can be fatal if untreated.

==Overview==
Lung rot appears after prolonged exposure to [[rot stink]], and affects both of a person's lungs. It can't be acquired from an [[event]].

The higher the [[rot stink|"rot stink" hediff]] severity, the more likely common the disease is. At 0.5 severity, there is an {{MTB}} of 8 days at 0.5 severity to get this disease. This goes up to a {{MTB}} of 0.5 days at 1.0 severity.{{Check Tag|Mechanics?|How does this scale? Linear or a curve?}}

Lung rot is not fatal if well-treated (some combination of good doctor, medicine, or facilities.) Each lung must be treated separately. As long as every treatment is 30% or higher, the disease will not progress. After 3-4 treatments over 6-8 days the disease will disappear.

===Prevention===
Preventing colonists from inhaling rot stink gas, which is done by avoiding rotten [[corpse]]s; a rot stink severity of at least 0.5 is required to contact lung rot. Try to avoid being in melee with [[scaria]]-infested [[animal]]s, as they will immediately rot on death. Otherwise, haul, [[grave|bury]], [[fire|burn]], or [[electric crematorium|cremate]] corpses in a timely manner, or wait for them to finish rotting.

In the [[Biotech DLC]]{{BiotechIcon}}, [[face mask]]s, [[gas mask]]s, and other sources of [[Toxic Environment Resistance]] all reduce the severity of rot stink.

[[Detoxifier lung]]s{{BiotechIcon}} are immune to rot stink. Each detoxifier lung also increases Toxic Environment Resistance, so if a pawn only has 1 artificial lung, the other one will be partially protected.

The [[perfect immunity]] gene{{BiotechIcon}} will prevent the acquisition of this disease but will not cure pre-existing conditions present at the time of implantation.

== Stages ==
These are the following stages in which lung rot will progress through, and the effects it has on the victim. Note that the effects are generally doubled as lung rot usually occurs in both lungs at the same time.

{| class="wikitable"
|-
! Stage !! Begins at !! Symptoms
|-
| '''Lung rot (minor)''' || 0 - 0.59 severity ||
* {{++|5%}} [[Pain]]
* {{--|5%}} [[Breathing]]
|-
| '''Lung rot (major)''' || 0.6 - 0.84 severity ||
* {{++|5%}} Pain
* {{--|10%}} Breathing
|-
| '''Lung rot (Extreme)''' || 0.85 - 0.99 severity ||
* {{++|10%}} Pain
* {{--|15%}} Breathing
* {{--|10%}} [[Consciousness]]
|-
| '''Lung rot (Extreme)''' || 1.00 severity ||
* [[Death]]
|}

=== Progression ===
*Severity increases by 0.300 per day.
*Treatment slows progression by a maximum of 1.000 per day.
**This means the disease will regress by 0.700 per day at 100% tend quality.
**Progression will pause at 30% tend quality or higher.
**Note that good treatment will not cause the disease to go away on its own.

The disease resolves after 4-8 days, independent of the patient's immune functioning. 

== Treatment ==
Treatment can be done using medicine which suppresses the disease, preventing it from reaching fatal stages. Pawns do not need to rest, as no immunity is gained.

As long as it is tended by a decent doctor, lung rot isn't particularly threatening to a pawn's life. The real downside is the time and medicine consumed for treatment, especially if many pawns get lung rot at the same time. It is possible to reach >30% tend quality even without medicine, if you have a great doctor and hospital setup.

== Version history ==
* [[Version/1.4.3523|1.4.3523]] - Added.
* [[Version/1.5.4062|1.5.4062]] - Rotstink exposure now causes lung rot in Core. Previously the effects were defined in Core, and the [https://store.steampowered.com/news/app/294100?emclan=103582791454681671&emgid=3294970071159733465 Steam announcement] for Update 1.4 mentioned it as a Core feature, however rot stink exposure and lung rot would not be applied without the [[Biotech DLC]].

{{Nav|disease|wide}}
[[Category:Disease]]

Skills

2026-01-07T15:58:57Z

Aelanna: Removing the unnecessary mining yield explanation as there's a link to the dedicated page for Mining Yield literally right below it.

{| align=center
| {{Character_Properties_Nav}}
|}
----

{{Rewrite|reason=Verbose and circumspect. Needs cleanup, better layout and general tightening up. Over used of italics and bold.}}
{{TOCright}}
[[File:skills_preview.png|right]][[File:skill_increase_anim.gif|268px|right|Increasing skills of a colonist that's currently building something.]]
Every pawn in RimWorld has a set of '''skills''' which govern their speed and success in the various types of [[work]].

Performing certain jobs will award '''experience points''' (XP) towards improving a pawn's skill, reflected by their skill '''level'''. A pawn's skill levels can be viewed by selecting the pawn with the cursor, then navigating to the Bio tab in the pawn inspect pane.
Pawns may have a '''Passion''' for a skill which increases the rate of XP gain and [[mood]], represented by an adjacent fire symbol in the pawn's Bio menu. Conversely, a skill may be entirely prevented by a pawn's [[backstory]] or [[trait]]s, which is represented by " -- " dashes in place of the level number.

A high skill level will grant improved speed and success in relevant jobs, up to Level 20. A low skill level will result in slow, poor performance at a related job, including Construction failure, wild animal revenge, surgery failure, low harvest yields, or poor [[quality]] crafting products.

Possible pawn skills are Shooting, Melee, Construction, Mining, Cooking, Plants, Animals, Crafting, Artistic, Medical, Social, and Intellectual.

== Summary ==
{{see also|Training}}
Skills are improved by performing certain associated jobs, although some few related tasks do not provide skill experience. Performing these tasks will earn the character experience points either per task completed or per second they are pursuing that task, both of which will eventually level up the skill. The resulting higher skill level then improves the performance in all associated tasks and types of work. Skills are leveled up individually, and there is no single "character level" as in many role playing games.

In some cases, special management tactics can be employed to more effectively or specifically steer the skill training in the colony, especially during periods of low work in colony development. See the [[Training|main article on skill training]] for more information.

=== Skills vs work types ===
Skills and work types (or "tasks") are two different, but related, concepts. In some cases, like "mine" (work type) and "mining" (skill), there is an almost perfect correspondence, but in many other cases there is not: the ''work types'' "tailor" and "smith", for example, are associated with the ''crafting skill''. Some tasks listed on the work tab do not even have an associated ''skill'' (eg. "haul", "clean" and "firefight").

The ''Work'' tab, where you assign tasks to colonists, indicates which skills are relevant for a given task (by mousing over a tick box). It also shows you if the colonist has a ''passion'' for those skills (with an icon in the tick box), and if a significant proficiency has already been acquired (by emphasizing the tick box border). Lower skill pawns have their work box darker, and higher skill pawns have it lighter. Extremely proficient pawns have a golden box. When assigning work to a pawn with low skill in a certain job, the box will have a red outline. Passions appear as extremely small flames at the bottom-right hand side of the work box. All these aspects are important for deciding how to assign tasks and types of work.

In general, you want colonists to perform tasks they are ''good at'' (it is productive for your colony), as well as tasks they are ''passionate for'' (improves the associated skill faster and also keep them happy while working).

=== Improving skills ===
{{Rewrite|section=1|reason=1) Other things affect GLF now, and table no longer accounts for every possible combination of GLF and passion 2) [[Ideoligion#Ranching]] precept inc effect and order of operations}}
Skill leveling in ''RimWorld'' is very similar to many role playing games: ''experience points'' are constantly earned, and the skill is ''leveled up'' when certain thresholds are reached. Importantly, the effect of a skill improves ''by level'', but it costs more and more XP to gain another level in a skill. This means that '''skill training is more effective the lower the skill level is.'''

When a player pawn gains a new level in a skill, a text mote will be displayed.

Experience points are generally gained at consistent rate per unit [[time]] - that is, while the rate may vary from one task to another, when performing a given task the only other factor is the time spent doing it. As higher skill levels often increase the speed a pawn performs tasks, this means that more tasks must be performed to spend the same amount of time working and thus gain the same amount of XP. This is not true for all tasks however, and some will simply give a lump sum of experience for each task completed.

Regardless of how XP is gained, it is multiplied by Passion and [[Global Learning Factor]] in the following way:

<code>Real XP gained = Global Learning Factor x [[#Passion|Passion Multiplier]] x Base XP gained </code>

Additionally, there is a soft cap of 4000 '''net''' XP gained per day per skill. Any XP gains past this point are multiplied by 20%.{{Check Tag|Clarify|How does this work for chunks of experience? If some action were assigned to give a lump sum of 5000 experience, would a pawn gain the full 5000, or would the pawn gain 4200?}} This cap resets a few seconds after midnight. Any XP losses will apply against the net gain (e.g. if a pawn were to gain 4500 XP, but lose 1000, they would still remain 500 XP under the cap). Experience from [[Skilltrainer]]s does not apply to this cap, nor is it affected by the 20% multiplier.

==== Passion ====
Passion for a given skill is indicated by the presence of flame icons next to the skill experience bar on the character's [[Bio]] tab. These passions increases the rate at which a pawn learns specific skills, and may provide them a [[mood]] boost when performing activities related to the skill. Skill gains from using a [[skilltrainer]] are influenced by ''passion'', making the item more valuable when used by characters with a passion for the associated skill. Typically, passion cannot be gained or lost in an adult pawn's lifetime, however [[children]]{{BiotechIcon}} may gain passions at [[Children#Growth moments|growth moments]] and the addition or removal of [[Genes#Aptitudes|Skill Aptitude xenogenes]]{{BiotechIcon}} can also affect passions.{{Check Tag|Incapable of?|What happens to passions on a suppressed skill when a pawns becomes incapable? Some tasks that use that skill can still be performed, despite the incapability and its effects are needed}}

The three levels of passion are:
{|
|-
| || '''''None: ''''' ||  No flames. 35% multiplier on experience gain. This is the most common passion level.
|-
| [[File:PassionMinor.png|24px|left]] || '''Interested: ''' ||  One flame. 100% multiplier on experience gain and +8 mood ("Minor passion for my work") while performing related tasks.
|-
| [[File:PassionMajor.png|24px|left]] || '''Burning: ''' ||  Two flames. 150% multiplier on experience gain and +14 mood ("Burning passion for my work") while performing related tasks.
|}

==== Global Learning Factor ====
{{See also|Global Learning Factor}}

A pawn has a default Global Learning Factor of 100%. Some traits, implants, Genes, and Hediffs can effect Global Learning Factor as an Offset, or a factor. Offsets are added to the base value of 100%. Then, the sum is multiplied by any applicable factors. For example, a pawn with the Fast Learner trait and a Learning Assistant implant has a final Global Learning Factor of 195%.

'''Offsets'''
* [[Too smart|Too Smart]] trait: {{+|75%}}, while also inflicting a penalty to [[Mental Break Threshold|mental break threshold]].
* [[Fast learner|Fast Learner]] trait: {{+|75%}}
* [[Slow learner|Slow Learner]] trait: {{--|75%}}
* [[Learning assistant]] implant {{RoyaltyIcon}}: {{+|20%}}
* [[Neural supercharger]] building {{IdeologyIcon}}: {{+|25%}}
* [[Gene#Quick study|Quick study]] gene {{BiotechIcon}}: {{+|50%}}

'''Factors'''
* [[Gene#Slow study|Slow study]] gene {{BiotechIcon}}: {{Bad|×50%}}

==== Experience multiplier table ====
{| class="wikitable"
|-
! Global Learning Factor !! 25% !! 45% !! 50% !! 70% !! 100% !! 120% !! 125% !! 145% !! 175% !! 195% !! 200% !! 220% !! 250% !! 270% !! 275% !! 295% !! 300% !! 305% !! 320% !! 325% !! 345%
|-
! ''None''
| {{#expr: 0.35* 25}}% || {{#expr: 0.35* 45}}% || {{#expr: 0.35* 50}}% || {{#expr: 0.35* 70}}% || {{#expr: 0.35* 100}}% || {{#expr: 0.35* 120}}% || {{#expr: 0.35* 125}}% || {{#expr: 0.35* 145}}% || {{#expr: 0.35* 175}}% || {{#expr: 0.35* 195}}% || {{#expr: 0.35* 200}}% || {{#expr: 0.35* 220}}% || {{#expr: 0.35* 250}}% || {{#expr: 0.35* 270}}% || {{#expr: 0.35* 275}}% || {{#expr: 0.35* 295}}% || {{#expr: 0.35* 300}}% || {{#expr: 0.35* 305}}% || {{#expr: 0.35* 320}}% || {{#expr: 0.35* 325}}% || {{#expr: 0.35* 345}}%
|-
! [[File:PassionMinor.png|frameless]]
| 25% || 45% || 50% || 70% || 100% || 120% || 125% || 145% || 175% || 195% || 200% || 220% || 250% || 270% || 275% || 295% || 300% || 305% || 320% || 325% || 345%
|-
! [[File:PassionMajor.png|frameless]]
| {{#expr: 1.5* 25}}% || {{#expr: 1.5* 45}}% || {{#expr: 1.5* 50}}% || {{#expr: 1.5* 70}}% || {{#expr: 1.5* 100}}% || {{#expr: 1.5* 120}}% || {{#expr: 1.5* 125}}% || {{#expr: 1.5* 145}}% || {{#expr: 1.5* 175}}% || {{#expr: 1.5* 195}}% || {{#expr: 1.5* 200}}% || {{#expr: 1.5* 220}}% || {{#expr: 1.5* 250}}% || {{#expr: 1.5* 270}}% || {{#expr: 1.5* 275}}% || {{#expr: 1.5* 295}}% || {{#expr: 1.5* 300}}% || {{#expr: 1.5* 305}}% || {{#expr: 1.5* 320}}% || {{#expr: 1.5* 325}}% || {{#expr: 1.5* 345}}%
|}

=== Decay ===
Beyond skill level 10, XP points are continuously drained away. A skill level is lost only after falling to 0 XP points, and then losing a further 1000 points, preventing repeated level loss and gain right around a level threshold. Experience decay is strictly calculated based on the current skill level and is not directly affected by skill use; Instead, gained XP simply cancels out loss, and vice versa.

XP decays at an accelerated rate with higher skill levels. This means that all XP earned after 55,000 total XP (level 10) effectively has less value, especially for skills that a colonist does not use frequently, because it will disappear. In most cases, XP is gained by ''time spent'' on a skill, and not by effective work performed: Working faster does not make it easier or faster to gain XP, or compensate the decay loss. Level 20 (max level) is very difficult to acquire, usually only achievable by colonists solely dedicated to a single profession.

The [[Great memory]] trait halves the skill decay rate for a pawn. The [[Perfect memory]] trait, which is only found on some [[Creepjoiner]]s,{{AnomalyIcon}} will entirely prevent all skill decay.

=== Skill point acquisition strategy ===
{{Stub|section=1|reason=Need at least simple introduction on which jobs and skills benefit from experts vs more hands and why - e.g. cooks beyond skill 9 = More hands, plant harvesting and crafting = experts.}}
The above implies that on average it is better to spread out the skill training over several colonists instead of having only one "expert", except for the artisan professions where it is usually good to have true experts in the colony.

For example, you need to acquire about 150,000 XP to make one colonist a "region-known master" (level 16); the same amount of XP would be enough to have ''three'' colonists at level 9 ("solid professional"). This avoids the risk of losing the only pawn that is capable of the task, and in most cases three level-9 workers are better than a single level-16 expert. Creating anything [[quality]] is a notable exception to this.

=== Experience table ===
Level 20 is the highest skill level achievable for a pawn.

{| class="wikitable"
|-
! Level
! Name
! Total experience required
! Experience till next level
! Experience decay rate (exp/day)
|-
| -
| Incapable
| -
| -
| -
|-
| 0
| Barely heard of it
| 0
| 1000
| 0
|-
| 1
| Utter Beginner
| 1000
| 2000
| 0
|-
| 2
| Beginner
| 3000
| 3000
| 0
|-
| 3
| Basic Familiarity
| 6000
| 4000
| 0
|-
| 4
| Some Familiarity
| 10000
| 5000
| 0
|-
| 5
| Significant Familiarity
| 15000
| 6000
| 0
|-
| 6
| Capable Amateur
| 21000
| 7000
| 0
|-
| 7
| Weak Professional
| 28000
| 8000
| 0
|-
| 8
| Employable Professional
| 36000
| 9000
| 0
|-
| 9
| Solid Professional
| 45000
| 10000
| 0
|-
| 10
| Skilled Professional
| 55000
| 12000
| 30
|-
| 11
| Very skilled Professional
| 67000
| 14000
| 60
|-
| 12
| Expert
| 81000
| 16000
| 120
|-
| 13
| Strong Expert
| 97000
| 18000
| 180
|-
| 14
| Master
| 115000
| 20000
| 300
|-
| 15
| Strong Master
| 135000
| 22000
| 540
|-
| 16
| Region-Known Master
| 157000
| 24000
| 840
|-
| 17
| Region-Leading Master
| 181000
| 26000
| 1200
|-
| 18
| Planet-Known Master
| 207000
| 28000
| 1800
|-
| 19
| Planet-Leading Master
| 235000
| 30000
| 2400
|-
| 20
| Legendary Master
| 265000
| 32000
| 3600
|}

Note that these values are considered before genes that affect skills. For example, a pawn with good social would only need 1000 experience points to get from level 4 to 5.

== List of skills ==
{{Split|section=1|reason=Split into individual skill pages and leave short summaries and links here. will allow better explanations of what trains each skill and how, and allow training considerations to be added}}
Using or applying skills will give ''experience'' in the skill, and improve the character's proficiency. How much experience is gained depends on the ''passion'' for the skill. See [[#Passion|passion]] below.

On this page, where experience gains are listed, an "Interested" passion with 100% skill gain is assumed. Note that this is not the "default" passion; "no passion" at 35% gain is far more common.

=== Animals ===
{{For|a list of skills that animals can learn|Animals#Training}}
The ''animals'' skill determines how well a character handles wild and domesticated animals, and increases the chance to go undetected while ''hunting'' wild animals.

Higher ''animals'' skill has the following benefits:
* Chance to tame a wild animal increases. Some animals can not even be attempted to be tamed if the ''animals'' skill is too low.
* Chance to successfully train a domesticated animal increases.
* Animal handling, such as ''milking'' and ''shearing'' certain livestock, becomes more efficient, with a lower chance of wasting products.
* Mastering an animal, as in having it follow you and obey your commands, becomes possible for more animal races. The more ''wild'' a race is, the higher the ''animals'' skill required to be assigned its master.
* It becomes less likely for a colonist hunting an animal to be detected by the animal, and the animal retaliating. It still requires ''shooting'' skill for the colonist to be able to kill the animal.
{{#ask: [[Category:Stat]] [[Skill::Animals]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Artistic ===
The ''artistic'' skill is the proficiency to create [[beauty|beautiful]] works of art at an [[art bench]].

Higher skill increases the chance for a higher quality, in this case more beautiful, sculpture. Note that higher skill levels do not increase the speed of creating sculptures.

The beauty and market value of sculptures increases tremendously at the highest quality levels. Combined with the fact that trade partners pay more for works of art compared to other items, this makes ''artistic'' a useful skill outside of decorating the home base.

Not very useful in the early game, but once you have a well-established colony, having a permanent artist would be beneficial to it.

=== Construction ===
The ''construction'' skill governs a wide variety of colonist tasks, centered around creating structures in the game world; it is an essential skill in any colony:
* Making all kinds of structures, like furniture, walls, power lines and spaceship parts. If a structure can be placed on the ground in form of a blueprint, its construction is usually facilitated by this skill. Many structures require a minimum skill to make.
* Deconstructing existing structures back into raw materials.
* Building and tearing down roofs.
* Laying and removing flooring, like carpet, concrete and stone tiles.
* Smoothing rock walls and stone floors.

Higher ''construction'' skill will
* allow the construction of more difficult to build structures.
* increase construction speed; the base speed at 0 construction skill is 50%, this is increased additively by 15% for every skill level.
* reduce the chance of a construction effort to be "botched", which will result in some resources going to waste, and require the construction effort to be restarted (ie. all work is wasted). The base chance of success is 75%, increasing by about 3% per skill level to 100% at skill level 8.
* increase the chance to make higher quality items, for items that have a quality rating, such as furniture.

Construction outcomes are influenced by the [[manipulation]] and [[sight]] capacities of the colonist.

Experience is gained continuously while working on a construction project. At 100% work speed this seems to translate to roughly 82 experience per point of work required.

{{#ask: [[Category:Stat]] [[Skill::Construction]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

<div><li style="display: inline-table;">
{| {{STDT| sortable text-center mw-collapsible mw-collapsed}}
|+ style="white-space: nowrap;" |'''Items with a required Construction skill level:'''
|-
! Name !! Level
|-
{{#ask: [[Skill 1::Construction]]
| ?Skill 1 Level=
| format = template
| template = Ask Table Formatter
| limit = 999
| link = none
| sort = From DLC, Skill 1 Level, Name}}
|}
</li><div>

=== Cooking ===
The cooking skill affects how long it takes to cook [[meals]] and butcher dead creatures, as well as the [[Food Poison Chance]] for the person who eats the meal. It also affects [[Butchery Speed]] and [[Butchery Efficiency]], how much meat is produced when butchering.

Cooking and butchering increase cooking skill. It is also trained by making [[smokeleaf joint]]s at a drug lab and cooking [[psychite tea]] at a campfire or stove.

A Cooking skill of {{Q|Lavish meal|Skill 1 Level}} is required to be able to cook every item, a skill of 9 achieves the minimum [[Food Poison Chance]], and a skill of 10 gives maximum [[Butchery Efficiency]] - assuming a healthy but otherwise unaugmented pawn. Levels above this only increase the speed of tasks.

{| class="wikitable"
|-
! Project
! Experience Given Per Task
|-
| Simple Meal
| 60
|-
| Fine Meal
| 110
|-
| Lavish meal
| 160
|-
| Pemmican
| 80
|}

{{#ask: [[Category:Stat]] [[Skill::Cooking]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

<div><li style="display: inline-table;">
{| {{STDT| sortable text-center mw-collapsible mw-collapsed}}
|+ style="white-space: nowrap;" |'''Items with a required Cooking skill level:'''
|-
! Name !! Level
|-
{{#ask: [[Skill 1::Cooking]]
| ?Skill 1 Level=
| format = template
| template = Ask Table Formatter
| limit = 999
| link = none
| sort = From DLC, Skill 1 Level, Name}}
|}
</li><div>

=== Crafting ===
The crafting skill affects the creation of many of the items under the [[Work#Smith|smith]], [[Work#Tailor|tailor]] and [[Work#Craft|craft]] work types. It does so in two ways; crafting quality and minimum crafting levels.

A pawn's Crafting skill is a driving factor in the [[Quality]] of produced [[Clothing]], [[Armor]], and [[Weapons]]. The quality of things such as [[Sculptures]] and [[Buildings]] are instead controlled by the [[#Artistic|Artistic]] and [[#Construction|Construction]] skills respectively.

The speed of production for these tasks is unrelated to Crafting level, however, and is instead completely dependent on a pawn's [[General Labor Speed]] and the amount of labor required in the bill.

Many work [[bill|bills]] of the [[Work#Smith|Smith]], [[Work#Tailor|Tailor]] and [[Work#Craft|Craft]] work types have a required minimum Crafting skill level. This restricts the creation of some items to skilled crafters regardless of their possible quality.

The Crafting skill also determines the time required to shred [[mechanoid]]s, and the amount of resources produced from doing so.

{{#ask: [[Category:Stat]] [[Skill::Crafting]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

<div><li style="display: inline-table;">
{| {{STDT| sortable text-center mw-collapsible mw-collapsed}}
|+ style="white-space: nowrap;" | '''Items with a required Crafting skill level:'''
|-
! Name !! Level
|-
{{#ask: [[Skill 1::Crafting]]
| ?Skill 1 Level=
| format = template
| template = Ask Table Formatter
| limit = 999
| link = none
| sort = From DLC, Skill 1 Level, Name}}
|}
</li><div>

=== Medical ===
{{Main|Doctoring}}

The ''Medical'' skill level is the main factor for medical treatment quality and speed, surgery speed and surgery success chance.

Low quality treatment will increase the chance of [[infection]], and the likelihood of permanent health conditions such as ''scars'', in turn leading to chronic pain. Certain scars cause more than 10% pain, permanently weakening the ''consciousness'' of the patient, which reduces their work performance.

Medical ''surgery'', if not successful, can fail in minor or major ways, even causing the death of the patient. The success rate is not only determined by the ''medical'' skill, but also other character stats like ''manipulation'', ''eye sight'' and ''consciousness''. It is not advisable to let an impaired doctor perform surgery.

Higher grade [[medicine]] and medical equipment like [[hospital bed]]s and a [[sterile tile|sterile]] environment significantly boost the effectiveness of all medical treatments, independent of the skill level of the doctor.

Medical skill can be trained very quickly by performing euthanasia on fast-breeding animals such as chickens. This costs 1 medicine per procedure, but only requires [[herbal medicine]]. The procedure can be scheduled in the respective animal's ''health'' tab, and an animal sleeping spot must be available to perform the euthanasia.

Performing ''surgery'' trains the ''medical'' skill. The amount of XP that is awarded only depends on the duration of the procedure (varying by procedure and ''medical operation speed'' of the surgeon).

{{#ask: [[Category:Stat]] [[Skill::Medical]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Melee ===
The melee skill determines a characters' effectiveness with [[melee weapons]] namely, their chance to:
* Land a hit in melee (''see [[Melee Hit Chance]]'')
* Dodge a melee attack, when not aiming or firing a ranged weapon (''see [[Melee Dodge Chance]]'')
The tables below are post-processed chances for a healthy pawn.
{{col-begin|width=60}}
<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">'''Chance to hit'''</div>
{| {{STDT| c_12 text-center}}
!Skill Level
!Standard
!Brawler
!Skill Level
!Standard
!Brawler
|-
!0
|50%
|62%
! -
| -
| -
|-
!1
|53%
|65%
!11
|81%
|85%
|-
!2
|56%
|68%
!12
|82%
|86%
|-
!3
|59%
|71%
!13
|83%
|87%
|-
!4
|62%
|74%
!14
|84%
|88%
|-
!5
|65%
|77%
!15
|85%
|89%
|-
!6
|68%
|80%
!16
|86%
|90%
|-
!7
|71%
|81%
!17
|87%
|90.3%
|-
!8
|74%
|82%
!18
|88%
|90.6%
|-
!9
|77%
|83%
!19
|89%
|90.9%
|-
!10
|80%
|84%
!20
|90%
|91.2%
|}
{{col-2|width=60}}
<div class="center" style="width:auto; margin-left:auto; margin-right:auto;">'''Chance to dodge'''</div>
{| {{STDT| c_12 text-center}}
!Skill Level
!Standard
!Nimble
!Skill Level
!Standard
!Nimble
|-
!0
|0%
|20%
! -
| -
| -
|-
!1
|0%
|22%
!11
|12%
|33%
|-
!2
|0%
|24%
!12
|14%
|33.5%
|-
!3
|0%
|26%
!13
|16%
|34%
|-
!4
|0%
|28%
!14
|18%
|34.5%
|-
!5
|0%
|30%
!15
|20%
|35%
|-
!6
|2%
|30.5%
!16
|22%
|35.5%
|-
!7
|4%
|31%
!17
|24%
|36%
|-
!8
|6%
|31.5%
!18
|26%
|36.5%
|-
!9
|8%
|32%
!19
|28%
|37%
|-
!10
|10%
|32.5%
!20
|30%
|37.5%
|}
{{col-end}}
{{#ask: [[Category:Stat]] [[Skill::Melee]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Mining ===
The mining skill determines how long it takes for a colonist to mine out each rock, and how much they can obtain from each mineral vein mined.

{{#ask: [[Category:Stat]] [[Skill::Mining]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Intellectual ===
This skill affects the speed at which [[research]] is completed.

{{#ask: [[Category:Stat]] [[Skill::Intellectual]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Plants ===
The plants skill affects how fast a colonist sows and harvests growing zones, hydroponics and flower pots, and how fast trees and other vegetation is cut down. It also influences how much a colonist [[Caravan#Foraging| forages]] while in a caravan. Some plants require a minimum plants skill in order to plant them.

{{#ask: [[Category:Stat]] [[Skill::Plants]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

<div><li style="display: inline-table;">
{| {{STDT| sortable text-center mw-collapsible mw-collapsed}}
|+ style="white-space: nowrap;" | '''Plants with a minimum Plants skill level to sow:'''
|-
! Name !! Level
|-
{{#ask: [[Category:Plants]] [[Minimum Required Growing Skill::>1]]
| ?Minimum Required Growing Skill=
| format = template
| template = Ask Table Formatter
| limit = 999
| link = none
| sort = From DLC, Minimum Required Growing Skill, Name}}
|}
</li><div>

=== Shooting ===
The shooting skill affects a character's [[Shooting Accuracy|accuracy]] with [[ranged weapons]].

The table below shows post-processed shooting accuracy per tile of distance for each skill level and trait combination, assuming the pawn is healthy:

{| {{STDT| c_12 text-center}}
!Skill Level
!Standard
!Careful Shooter
!Trigger-Happy
!Skill Level
!Standard
!Careful Shooter
!Trigger-Happy
|-
!0
|89%
|94.5%
|84%
! -
| -
| -
| -
|-
!1
|91%
|95%
|85%
!11
|97.25%
|98.333%
|95%
|-
!2
|93%
|95.5%
|86%
!12
|97.5%
|98.5%
|95.5%
|-
!3
|93.5%
|96%
|87%
!13
|97.75%
|98.666%
|96%
|-
!4
|94%
|96.5%
|88%
!14
|98%
|98.833%
|96.5%
|-
!5
|94.5%
|97%
|89%
!15
|98.167%
|99%
|97%
|-
!6
|95%
|97.25%
|91%
!16
|98.333%
|99.125%
|97.25%
|-
!7
|95.5%
|97.5%
|93%
!17
|98.5%
|99.25%
|97.5%
|-
!8
|96%
|97.75%
|93.5%
!18
|98.666%
|99.313%
|97.75%
|-
!9
|96.5%
|98%
|94%
!19
|98.833%
|99.375%
|98%
|-
!10
|97%
|98.167%
|94.5%
!20
|99%
|99.438%
|98.167%
|}

Note that shooting accuracy for the pawn is calculated '''per tile''', meaning that while a trivial increase (like 1% or so) in shooting accuracy may not matter up close, it can make a huge difference in long distances.

For example:
*A colonist with shooting accuracy of 99% has a base accuracy of 72.5% against a target 32 tiles away.
*With 98% accuracy, the base accuracy against the same target becomes only 52.4%.

The base accuracy at various distances are listed when you check the information of a pawn. This can show the actual shooting performance of a pawn, especially at long ranges.

{{#ask: [[Category:Stat]] [[Skill::Shooting]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

=== Social ===
The social skill affects the impact of social interactions on other characters' mood, the impact of gifts on faction relations, the recruitment chance for prisoners and trader prices.
A small amount of experience is gained every time two colonists have a social interaction with each other. Characters have a [[talking]] stat that somehow interacts with this skill

{{#ask: [[Category:Stat]] [[Skill::Social]]
| ?Description
| ?Skill Base Factor=Base Factor
| ?Skill Bonus Factor=Bonus Factor
}}

== Version history ==
* [[Version/0.0.245|0.0.245]] - Skills now cap at 20. Added cooking, medicine, artistic, crafting but currently do nothing. Rebalanced shooting and melee to make skill more important. Shooting accuracy split into misses due to equipment and misses due to skill.
* [[Version/0.2.363|0.2.363]] - High level skills now decay. Passions system added.
* [[Version/0.9.722|0.9.722]] - Old pawns now tend to spawn with higher skills. Low skill cooks can now cause food poisoning.
* [[Version/0.10.785|0.10.785]] - Passion flames are now displayed subtly on the work overview screen. Reduced skill degradation rate. Reworked how skills generate so there will be more initial skill variation and age affect starting skills more.
* [[Version/0.12.906|0.12.906]] - Animals skill added.
* B19/1.0 - Doing passionate work now affects mood instead of recreation. Adjusted balance of learning rates for various skills. Easier: Melee, shooting, social. Harder: Intellectual, growing, mining.
* [[Version/1.2.2753|1.2.2753]] - Pawns will now not lose their skill levels until they fall 1000 XP under zero. This stops pawns from quickly leveling up and down around a threshold. We now display a text mote when a player pawn gains a new level in a skill.
* [[Version/1.4.3527|1.4.3527]] - Fix: Can train shooting and melee on colony mechanoids.

[[Category:Characters]]

Molotov cocktails

2026-01-07T15:47:22Z

Aelanna: Corrected explosion from damage threshold. Verified via decompiler -- this is the default value for CompExplosive as molotovs do not override the default.

{{Infobox main|weapon
| name = Molotov cocktails
| image = Molotov.png
| description = Glass bottles filled with flammable liquid, with a burning cloth in the neck. A favorite weapon for hooligans and desperate warriors from rim to rim.
| type = Equipment
| type2 = Weapons
| tech level = Industrial
| class = Industrial
| damage = 10
| damage type = Flame
| mode = Single Thrown
| warmup = 90
| cooldown = 160
| burst = 1
| aimSub = 3.8
| range = 12.9
| accuracy = -
| DPS = DPS
| velocity = 12
| missRadius = 1.9
| blastRadius = 1.1
| production facility 1 = Machining table
| research = Machining
| resource 1 = Cloth
| resource 1 amount = 25
| resource 2 = Chemfuel
| resource 2 amount = 80
| marketvalue = 245
| work to make = 6000
| work speed stat = General Labor Speed
| mass base = 1.0
| has quality = False
| weaponTags = GrenadeDestructive, GrenadeFlame
| tradeTags = WeaponRanged
}}
'''Molotov cocktails''' are short ranged, thrown [[weapons]] that have a forced miss radius but deal flame damage and set a 3x3 "plus-shaped" ('''+''') area on fire where they land. They are not consumed on use and do not use any ammo.

== Acquisition ==
{{Acquisition}}

They can also be [[Trade|purchased]] from orbital pirate merchants and orbital combat suppliers, [[outlander]] [[faction base]]s, or obtained from the following [[raider]] kinds:


{| class="wikitable sortable"
! Raider Kind !! Chance !! Average Quality !! Health
|-
| [[Raider#Grenadier|Grenadier]] || 50% || Normal || 70-230%
|}

== Summary ==
[[File:Molotov cocktails.png|thumb|left|200px|Molotov cocktails range and AoE]]

=== Weapon ===
Molotov cocktails are weapons. They take up the weapon slot and will not run out of ammo. They are blocked by walls, but the blast ignores [[cover]]. When choosing a target, a circular zone will generate to indicate range, then another 3x3 indicator with a circular center will become the aiming spot.

Molotovs deal {{P|Damage Base}} [[Damage types#{{P|Damage Type}}|{{P|Damage Type}}]] damage in a {{P|Blast Radius}} tile radius. They are thrown from a very short range of {{P|Range}} tiles and have moderate aiming time; they explode immediately on landing. With a forced miss radius of 1.9 tiles, an unobstructed molotov always lands within 1 grid tile (including diagonals) of the target. This means [[Shooting]] skill, [[shooting accuracy]], and health of the grenadier is irrelevant. [[Aiming time]] effects still apply, however.

Flame damage will possibly ignite pawns. The impact will create [[Filth#Chemfuel puddle|chemfuel puddles]], which will then ignite and burn, causing general [[fire]]s.{{Check Tag|Puddle behavior?|Are there always 5 puddles, do they always ignite etc.}} Pawns on fire will run wildly and are unable to attack.

{{Pyromaniac Weapon Note}}
=== Item ===
When damaged with [[Damage Types#Flame|Flame]] damage below 20% of its health, the cocktails will spark and emit a hissing sound shortly before exploding some time later. The explosion deals 10 Flame damage in a 2.66 tile radius around itself, without leaving chemfuel puddles. They cannot be smelted in an [[electric smelter]].

Molotov cocktails have no [[quality]] - every set of molotovs will have the same stats, regardless of the skill of the crafter.

== Analysis ==
=== Combat ===
Molotovs are dubious in raw combat. Molotovs are better in a supporting role, being one of the few weapons that start fires. Pawns that are on fire will stop attacking and run wildly, making them easy targets. But fire on its own isn't very strong, molotovs have a short range, and fire can lead to collateral damage. Without manual oversight, grenades are inefficient against moving targets. However, due to the forced miss, they can be a viable alternative weapon for pawns with low shooting skill or health issues.

When throwing a cocktail down an 1-tile wide alley, a pawn can consistently throw a cocktail 4 tiles, not including the tile the pawn is standing on, without intersecting the two side walls. Beyond 4 tiles, there is a risk of hitting the wall and dropping short. This can be relevant to prevent friendly fire or damaging defenses during combat. Watch out when using these in place of [[frag grenades]] when melee blocking, as the fire can allow enemies to clip past your blockers, allowing them to surround the blockers or attack your backline.

Because it relies on fires, [[rain]] significantly diminishes its outdoor utility. Note that the game has a "firewatcher", and will automatically start rain if fires get too out of control.

=== Fire traps ===
Molotovs become much more useful as a general firestarter. Burning down flammable structures is a very powerful tactic, though it can be costly.

Place fuel like wooden [[barricade]]s or [[straw matting]] where you want things to burn. Then, lure and trap [[raider]]s (or other enemies) inside.
* In a mountain, you can use fire to burn any [[infestation]]s that spawn inside your pawn's bedrooms.
* You can use wooden [[column]]s/walls as fuel, and use them to support [[roof]]s. In the absence of other support, burning the wall will cause a [[Roof#Roof_collapse|roof collapse]].

In a dedicated "oven" or "burn tunnel", fire can kill infinitely many human pawns. So long as a place is [[roof]]ed and "Indoors", temperatures will rapidly rise. As [[heatstroke]] is the way most pawns are [[downed]], no amount of heat protection will save an organic pawn. Note that [[mechanoid]]s are completely immune to both fire and heatstroke. Heatstroke ignores the usual [[AI Storytellers#Enemy death on downed|death on downed]] chance with combat, allowing you to easily capture pawns and recover untainted [[armor]].

<gallery widths="400px" heights="400px" class="left" mode="nolines">
File:Ancient danger fire.png|'''Fire being used to handle an [[ancient shrine]]'s cryptosleep caskets, once the initial threats are cleared.<br>Place some fuel, toss molotovs from outside until the room reaches ~ {{Temperature|400}}, then shoot the caskets to open them. '''
File:Ancient danger fire2.png|'''Even with [[firefoam pop pack]]s: it isn't the fire that kills, its the heatstroke (usually).<br>Deconstructing 1 wall will make the room "Outside", turning it from 800°C to 23°C. This allows you to easily capture pawns, untainted armor, and the rest of their gear.'''
</gallery>

=== Utility ===
Fire is very useful to dispose of flammable items, like [[corpse]]s. Simply gather all unwanted items in a fireproof room (like using stone for walls and floor), draft a pawn, and throw the cocktail. Make sure to remove the Home Area around the room, so that pawns don't try and extinguish the fire. Molotovs throw faster and are significantly cheaper to produce than [[incendiary launcher]]s, so are better for this purpose. For [[corpse]]s, watch out for [[rot stink]]; haul corpses quickly and wait for the rot to wear before burning.

In extremely cold temperatures, fire can be a last resort in order to create [[temperature|heat]]. Use with extreme caution - fire can quickly go out of control, and temperatures easily get too hot. Typically, colonies with access to molotovs also have access to [[heater]]s.

== Version history ==

* 1.0 - Received a crafting recipe.
* [[Version/1.3.3066|1.3.3066]] - Grenade throws are rendered in an arc.

{{Nav|weapon|wide}}
[[Category:Equipment]] [[Category:Weapons]] [[Category:Industrial Weapons]] [[Category:Flame Weapons]]
[[Category:Ranged Weapons]] [[Category:Single Thrown Weapons]]

Golden cube

2026-01-07T15:32:41Z

Aelanna: Correcting the gold drop amount - verified via decompiler.

{{Anomaly}}
{{Spoiler}}
{{Stub|reason=Requires confirmation on effects, compilation of disposal methods, information on anomaly study, etc.}}
{{About|the miscellaneous object added by the [[Anomaly DLC]]|the object used in an [[Ideoligion]]'s [[Reliquary]]|Relic}}
{{Infobox main|entity
| name = Golden cube
| image = Golden cube.png
| description = A cube that fits snugly in the hand. Golden in color, it is always invitingly warm to the touch, like a trusted pet or a hug from a good friend. Those that look closely are rewarded for their attention by the delightful way light plays across its welcoming surface.<br />The cube seems impervious to most damage.

| type = Entity
| type2 = Advanced
| market value = 1200
| mass base = 1
| beauty = 400
| flammability = 0
| rotatable = false
| path cost = 14

| anomaly knowledge = 2
| knowledge category = Advanced
| study interval = 120000
| min monolith level for study = 1
| show toggle gizmo = true

| defName = GoldenCube
| label = golden cube
| category = Item
}}
The '''golden cube''' is an inanimate [[entity]] item added in the [[Anomaly DLC]].

== Acquisition ==
There are two ways to acquire the golden cube:
* The [[Mysterious cargo]] quest involves either a neutral/allied planetary [[faction]] or an anonymous AI asking you to take an unspecified item off their hands, along with a sizable payment. One of the =randomly selected options for the cargo is the golden cube. For further information about the quest, see that page. The golden cube appears with a blue "Mysterious Cargo" letter when it lands on your map.
* Performing the [[Void provocation]] ritual can result in the appearance of a golden cube on your map. The monolith must be at least at Level 2 for the Golden Cube to appear after a Void Provocation. The golden cube appears with an orange "Golden Cube" letter when it appears on your map via Void Provocation.
* Note that these events can stack in order to acquire multiple cubes at the same time, posing a bigger hindrance than "only" one cube.

== Summary ==
At first glance, the golden cube is a harmless - if useless - item, which can be [[haul]]ed, [[stockpile]]d, carried, and [[caravan]]ed with no apparent effect. However, its presence on the map will gradually produce a powerful, deleterious influence on your colonists. This influence will only stop once the cube has been [[#Deactivation|deactivated]], though not without further consequences. The cube cannot be destroyed until it has been deactivated, and despite its significant market value, it cannot be sold under any circumstances.

=== Containment ===
Unlike most anomalous [[entities]], the cube does not need to be contained or suppressed. It can simply be kept in storage until pawns move to study or play with it. Each study session produces a total of 2 advanced knowledge, and it can be studied every 2 days. You can, however, prevent pawns from interacting with it by forbidding it. This prevents obsession from worsening, but will not stop the cube from choosing new victims.
{{Check Tag|Detail Needed|If the cube is placed in a caravan, will it affect the caravaneers? If so, will it affect them, or colonists on a map, as well? Will it affect pawns if placed in an Odyssey DLC shuttle?}}

=== Cube interest ===
{{Quote| "This person is drawn to the golden cube. If separated from the cube for too long, they'll start to experience negative effects."}}
When the cube spawns on the map, one [[colonist]] will immediately gain the cube interest health effect. Over time, other colonists will become afflicted as well. On average, another colonist becomes cube interested every 12 days. Once a pawn becomes interested, however, they will experience a series of buffs and debuffs that get more severe as the affliction progresses, and severe negative [[thought]]s if they don't interact with the cube regularly.

Initially, the effects are fairly benign; a cube-curious pawn will begin at 10% interest, and will stop work to play with the cube roughly once a day. This takes one in-game hour and cannot be interrupted once it begins except by drafting them. Additionally, all social interactions they engage in will now involve talking about the cube, "Wandering" activity wil now be called "Wandering and thinking about the cube." and psyfocus meditation will be changed to "Meditating on the cube." but all three are purely cosmetic changes. In exchange, the pawn experiences the {{Thought|label= Cube Joy|desc= My wonderful cube. My precious cube. I love it. It's so beautiful.|value=+15|stack=1|duration=1}}. Each interaction with the cube increases a pawn's interest level by around 6 to 9 percent, progressing the pawn to more disruptive behaviors. You will receive a notification each time a pawn's obsession worsens.

At any interest level over 10%, your affected pawns will occasionally stop work to build [[cube sculpture]]s, curious artistic objects that provide a small amount of beauty but require no resources. Although the sculptures are marginally useful, these mental breaks can occur at any time, including in the middle of combat. Frequency of these events is tied to the interest level, occurring rarely at first but multiple times a day as a pawn's interest reaches its later stages. Also, be aware that destruction of these sculptures can result in severe mood penalties and berserker mental breaks.

Interest over 33% is considered "Fascinated." Along with the previous effects, these pawns now have a small chance{{Check Tag|Frequency?}} of suffering random mental breaks during which they wander in a daze, thinking about the cube. They are also distracted from their tasks the rest of the time, working at only 90% normal speed. This is balanced out slightly by the fact that their Sleep level falls at 80% its normal rate.

The final stage - "Obsessed" - sets in once interest level reaches 66%. At this stage, the sculpture and daze events occur more frequently,{{Check Tag|Frequency?}} and the modifiers your pawns experience are doubled: 60% Sleep fall rate and 80% work speed. On top of that, your pawns suffer a +4% penalty to their mental break threshold. Given how much time your pawns spend doing cube-related activities - none of which have any impact on Recreation - your pawns will soon find themselves either miserable and Recreation-deprived or unable to find time to do actual work.

The alternative to allowing your pawns to progress their interest is to forbid the cube. So long as the item is forbidden, your pawns will be unable to worsen their interest, instead going into cube withdrawal.

{| class="wikitable" style="text-align:right;"
! Level
! Severity
! [[Sleep|Sleep Fall Rate]]
! [[Work|Global Work Speed]]
! Other effects

|-
! Curious (Initial)
| 0-10%
| x100%
| x100%
| Occasionally play with cube or suffer withdrawal.

|-
! Curious
| >10%
| x100%
| x100%
| Same as above, plus chance of cube sculpture mental break.

|-
! Fascinated
| >33%
| {{Good|x80%}}
| {{Bad|x90%}}
| Same as above, plus chance of cube daze mental break.

|-
! Obsessed
| >66%
| {{Good|x60%}}
| {{Bad|x80%}}
| Same as above with greater frequency, plus {{Bad|+4% Mental Break Threshold}}.
|}

==== Cube sculptures ====
{{Split|section=1|destination=Cube sculpture|reason=Would be easier to do stats atc. - leave brief summary here, with link to that page }}
{{Main|Cube sculpture}}
Cube-Fascinated colonists will go on periodic mental breaks {{Check Tag|MTB?|How often?}} during which they will build a [[sculpture]] related to the cube. The building speed and quality of the sculpture is affected by construction skill. The quality can be of any value, starting at awful for a 0 beauty score. 2 for poor, 4 for normal, 8 for good, 12 for excellent, and 20 for masterwork. Be aware that this sculpture will use up a [[Inspired creativity]] inspiration, if the colonist has one.

The type of sculpture generated depends on the [[terrain]] or [[floor]]ing the colonist is standing on or by - no material is actually consumed to create the sculptures. The sculpture types and the related terrains are listed in the table below:

{| class="wikitable collapsible"
|+
|-
! Sculpture type !! Terrains
|-
| Dirt cube sculpture ||
* Marshy soil
* Mud
* Packed dirt
* Rich soil
* Lichen-covered soil
* Soil
|-
| Sand cube sculpture ||
* Sand
* Soft sand
|-
|| Stone cube sculpture ||
* Rough stone
* Rough-hewn stone
* Smooth stone
|-
| Scrap cube sculpture || ''All other terrains and floors''
|}
The different types of cube sculpture vary in name and texture but are otherwise statistically identical. The sole exception to this is that scrap cube sculptures have 40% flammability while all other have 0%.

The sculpture, once complete, can be freely minified and moved, but it cannot be deconstructed. It must be destroyed with attacks.

While the cube statue exists its sculptor gets {{Thought|label=Cube Sculpture|desc= My sculpture... My beautiful Sculpture!|value= +1}}. This stacks with each cube sculpture they've created, without an apparent limit. If the sculpture is destroyed, the sculptor will get {{Thought|label= My Cube Sculpture Destroyed|desc=My sculpture... My beautiful sculpture... |value= -5| stack=10 | multi= 0.75|duration=5}} and an increase in severity to a hidden "Cube anger" hediff. Each destroyed sculpture yields an increase in Cube Anger severity that scales with the current cube interest of the pawn. This hediff is hidden, and so its progress cannot be normally tracked.

The increase in severity is controlled by the following relationship:
{| class="wikitable"
|-
!
{{Graph:Chart
|width=400
|height=100
|type=area
|xAxisTitle=Cube interest (%)
|yAxisTitle=Cube anger per sculpture destroyed (%)
|xAxisMin=0
|yAxisMax=100
|x= 10, 50, 100
|y= 10, 20, 40
}}
|}

Once the Cube Anger hediff reaches 100% severity, the pawn will go into a [[Berserk]] mental state with an {{MTB}} of {{Ticks|60000*0.04}} along with a custom [[letter]] detailing the cause. Once the pawn has gone into the rage, the Cube Anger hediff is reduced to 0% and removed. The only other way to remove the accrued Cube Anger besides an eventual berserk state, is for the affected pawn to die. The hediff will no longer be present upon resurrection.

==== Cube withdrawal and coma ====
{{Quote| "This person obsessively wants to find their golden cube. Their skin itches and their mind races, thinking of ways to get closer to the cube. Their symptoms will get worse until they play with the cube."}}
{{Quote| "This person was connected to a golden cube and then separated from it. Severing the link this way has put them in a coma."}}

If an obsessed colonist is prevented from playing with the cube for an extended period of time, they start going through withdrawal. When they do, they get the "Cube Withdrawal" health condition. Cube withdrawal worsens more quickly for colonists with advanced cube obsession{{Check Tag|Detail needed| How much per day by obsession level?}}. Cube withdrawal inflicts a gradually increasing penalty to consciousness, accompanied by a potent {{Thought| label= Cube Withdrawal | desc= I need to see the golden cube. Just once more. Please. / Where's that cube? I miss it. I need it! / Where is my cube? Where is it? | value=-15 | value2=-20| value3=-30| stack = 1}} debuff. If cube withdrawal is allowed to progress to 100%, the colonist will fall into a cube coma, multiplying their consciousness level by 10%. The coma can last anywhere from 3 to 24 days, depending on the colonist's obsession level. Upon waking up from the coma, the colonist will no longer be obsessed with the cube. However, nothing prevents the recently woken colonist from becoming obsessed with the cube again.

{| class="wikitable" style="text-align:right;"
! Level
! Severity
! [[Consciousness]]
! [[Mood]]
! Notification

|-
! Initial
| >10%
| {{Bad|-10%}}
| {{Bad|-15}}
| [Name] is experiencing cube withdrawal.

|-
! Moderate
| >35%
| {{Bad|-15%}}
| {{Bad|-20}}
| [Name]'s cube withdrawal has worsened.

|-
! Extreme
| >65%
| {{Bad|-20%}}
| {{Bad|-30}}
| [Name]'s cube withdrawal has worsened.
|}

=== Deactivation and destruction ===
Once at least 4 research has been gained from the cube, you will receive a letter hinting at the cube's addictive impact on your pawns. It further states that the cube can be destroyed, but more research is needed to determine how. Although the letter says that the pawn studying it needs to study it to learn more, any pawn may perform research to further the investigation. Studying the cube has no risk of addiction.

{{Quote| "{PAWN_nameDef}'s investigation of the golden cube has revealed more. It is able to psychically influence anyone who interacts with it. Those under the cube's influence will experience extreme withdrawal if they're separated from it.\n\n{PAWN_nameDef} thinks that there may be a way to deactivate the cube, but {PAWN_pronoun} will need to study it further."}}

Once a total of 24-40 research has been gained from the cube, an option to permanently deactivate it becomes available. Doing so requires 1 [[Archotech]] [[Shard]] and can only be done by a pawn not currently suffering from cube obsession, destroying the cube and breaking its hold over your colony. However, this event will send any colonists under the cube's influence who are not already in a cube coma into [[Berserk]] Mental Breaks, even if on other map tiles. Pawns in [[caravan]]s at the time of this deactivation instead leave your colony permanently, so be sure to avoid deactivation while addicts are travelling. If you intend to destroy the cube with conscious addicts present, expect to lose pawns and keep your doctors safe so they can treat the injured.

To find exact info on how much you have and how much you need to research the GoldenCube you can open your save file with an editor, such as notepad++, to find code entry:
<anomalyKnowledgeGained>##</anomalyKnowledgeGained> and <studyThresholds>##,##</studyThresholds> under <def>GoldenCube</def>
The first entry is to find you total research on the cube the second entry is to identify exactly what the research needed is to get event completion the first threshold is always 4 as mentioned above.

There are simple measures you can take to avoid these violent mental breaks. Colonists already in a cube coma will simply wake up, cured of their addiction. Any obsessed colonist that is anesthetized when deactivation occurs will ignore the event and be free of cubic influence when the anesthesia wears off. It is not yet confirmed if [[mind-numb serum]] can prevent these mental breaks{{Check Tag|Mindnumb?|Mindnumb serums appeared to mostly work, but one of my 9 obsessed colonists, who had been mindnumbed, still berserked. It could be that only currently awake pawns can berserk? Seems to be tied to onlyTargetControlledPawns, from my rudimentary examination of the defs}}.

Be aware that colonists in [[cryptosleep casket]]s are ''not'' protected. They will immediately wake up, escape, and begin rampaging. One unorthodox but cheap and effective method to keep your colony safe from cube berserkers is to draft the afflicted pawns and trap them in isolated 3x3 wall prisons. When they go berserk, they will be unable to inflict any damage before the state wears off. Afterwards, simply deconstruct the walls to release them. Although time-consuming to set up, this approach only costs a small amount of wood.

If your entire colony is afflicted, deactivation of the cube is still possible with the help of temporary pawns from quests. Note that there is a small, but not insignificant, chance that new temporary pawns may become obsessed with time. Therefore, if you are relying on a newly joined pawn to deactivate the cube it should be done as soon as possible.{{Check Tag|Detail needed|Confirmed for desperate refugees and pawns accepted for hospitality, can other temporary pawns become obsessed? Do clones from the Warped Obelisk also have cube obsession?}}. Children (ages 3-12), since they cannot do research yet, cannot be enthralled by the cube, and so a child can be used to manually deactivate the cube while your adults are isolated, anesthetized, or otherwise rendered inoperable.

Alternatively, you can dispose of the cube via caravan dumping or [[transport pod]], but doing so does not remove your colonists' obsession. Unless the cube is deactivated and destroyed, your colonists will have to go through withdrawal, coma, and recovery.

Upon deactivation the golden cube drops 125-175 [[Gold]]. The exact amount dropped is completely random and is not affected by how many colonists were affected by it nor by any skill value.

[[Deathrest]] and [[Anesthetic|Anesthesize]] prevents a pawn to becoming berserk when the cube is deactivated.

=== Multiple cubes in one colony ===
While multiple cubes in the same colony result in a much higher rate of addiction the deactivation of one cube cures ALL colonists. So there is no separate addiction for the two cubes.

== Analysis ==
As with any anomalous object, care should be taken when a cube arrives. It is one of the safest advanced entities you can encounter, but can still prove frustrating as it drops productivity to a crawl. This is especially true for colonies with low populations: the loss of two or three pawns to low productivity is much easier to bear when you have others to handle their burden. So long as you have your researchers aggressively studying the cube every two days, you should be able to deactivate it before it influences many of your colonists. Dosing your best researcher with [[voidsight serum]] or making use of an occultist [[creepjoiner]] can speed up research dramatically. Once you unlock the option to destroy the cube, simply anesthetize the cube's victims before deactivation and the threat will be safely dealt with.

However, if you decide you wish to roleplay as a cube cult and keep it around, this is not entirely impossible. The introduction of the cube will gradually cut into your overall productivity, but will also grant a substantial mood bonus to any colonist allowed to consistently interact with it. Colonies with many pawns who are constantly in danger of mental breaking may find this useful, as the sizable mood buffs will change potentially dangerous mental breaks into smaller sculpture creation breaks. However, constant sculpting can prove troublesome as it not only wastes a pawn's time, but also takes up space with relatively low value sculptures which cannot be broken without a mood penalty.

The cube itself has a considerably high [[beauty]] value (about on par with a Good quality golden statue) which can even increase the mood of pawns who are not obsessed but simply share the same room as the cube. This can quickly increase the beauty value within a room colonists frequent, such as a rec room or dining room. Keeping the cube on display may prove difficult, though, as your pawns will attempt to play with it constantly. This may limit the display time and relocate the golden cube afterwards. Placing a dedicated 1x1 [[Stockpile zone]] for the cube can ensure that it always returns to a specific viewing point. Using a [[shelf]] instead will negate its beauty entirely.

Caravans are made substantially more difficult to form and maintain as any affected colonists will eventually be plagued with constant mood penalties and even a coma due to undergoing cube withdrawal{{Check Tag|Verify|Does carrying the cube within a caravan change this?}}. Often, you may be restricted to keeping any obsessed colonists at home while unaffected pawns can safely do quests on the world map.

It is desirable for pawns with [[tortured artist]] trait to be obsessed with the cube, as the frequent but harmless mental break will still give them creativity inspiration. If you suspect the mysterious cargo is the cube, you can give a pawn interest by knocking out everyone else or moving them off the map with a caravan before accepting it.

== Version history ==
* [[Anomaly DLC]] Release - Added.

{{Nav|entity|wide}}
[[Category: Entities]]

Modding Tutorials

2026-01-05T04:56:25Z

Aelanna: /* Art Tutorials */

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)
* [[Modding_Tutorials/Code_FloatMenuOptionProvider|FloatMenuOptionProvider]] - How to use <code>FloatMenuOptionProvider</code> to add right click context menu options to arbitrary targets.

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
* [[Modding Tutorials/Rituals]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* Ekksu's animal texture guides: [https://imgur.com/a/how-to-make-rimworld-sprites-its-basically-x-with-y-edition-wS3Pt 1] [https://imgur.com/a/how-to-make-rimworld-sprites-theres-nothing-that-looks-like-this-animal-edition-xdDzg 2]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials

2026-01-05T03:30:58Z

Aelanna: Removing Ekksu's guide as it's now a dead link.

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)
* [[Modding_Tutorials/Code_FloatMenuOptionProvider|FloatMenuOptionProvider]] - How to use <code>FloatMenuOptionProvider</code> to add right click context menu options to arbitrary targets.

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
* [[Modding Tutorials/Rituals]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials

2026-01-05T03:25:04Z

Aelanna: Removed Plague Gun from the dangerously outdated section as it's actually in the approved list.

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)
* [[Modding_Tutorials/Code_FloatMenuOptionProvider|FloatMenuOptionProvider]] - How to use <code>FloatMenuOptionProvider</code> to add right click context menu options to arbitrary targets.

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
* [[Modding Tutorials/Rituals]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Plague Gun

2026-01-05T03:21:57Z

Aelanna:

{{DISPLAYTITLE:Plague Gun}}

{{BackToTutorials}}

This is a tutorial for taking an item [[mod]] from conception all the way to completion, touching on most systems involved in RimWorld modding and explaining each step.

'''Editor Note:''' This tutorial is somewhat obsolete as custom C# code is no longer necessary to apply additional hediffs to the target of a ranged attack, however it has been kept here as it still serves as a useful end-to-end tutorial on how to set up a custom code assembly for a RimWorld mod. This particular version was first written for RimWorld v1.1, but has been updated and should still work in v1.6, if you run into any issues please let us know in in the #mod-development channel of the [https://discord.gg/UTaMDWc RimWorld Discord].

== Introduction ==

In this tutorial we will be using most of the tools available to a Rimworld [[Modding|modder]] to create a custom weapon, known as the Plague Gun.

This weapon will, when its shots hit a living target, have a chance to apply the [[Plague]] hediff ("health difference") to that target.

To do this, we will create XML ThingDefs for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.

This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.

If you have no XML or C# experience, there are good tutorials for XML [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

Make sure to have the following installed, at least one per row:

{| class="wikitable"
|-
| [https://code.visualstudio.com/ VSCode] || A text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

In this stage we will set up the mod and create XML files which add our things to the database.

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a <code>Mods</code> folder (if it doesn't already exist).
<br /><nowiki /><small>RimWorld>Mods>PlagueGun</small>
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About</small>
# Inside the '''About''' folder, make a new text file and rename it About.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>About.xml</small>
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|required items]]. I always make a .txt file first and change it to .xml. If you can't rename your file's type, make sure you have filetypes visible in your operating system's file view settings.
#* [[About.xml]] is the file that shows your mod in the mod list inside the RimWorld game. It is also used when creating a Workshop upload for Steam.
#* At the top of an XML file, always include this for RimWorld. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''Note: the'' version '' tag should always be "1.0". It has no relation with the current RimWorld version.''
#* Then add the MetaData tags for the Workshop and in-game Mod list.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<li>1.1</li>
</supportedVersions>
<description>This mod adds a plague gun, a weapon that has a chance to give your enemies the plague.\n\nFor version 1.1.</description>
</ModMetaData>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>Preview.png</small>
#* This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop.
#* The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb.
#* Example: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs</small>
#* RimWorld will read your XML files in any subdirectory of '''Defs'''. You can name your directories however you like under that folder. Defs>StrangeNewAlienGuns>MyGuns.xml will work. For the purposes of this tutorial, however, we will use the RimWorld standard structure.
#* What are Defs? Main article: [[Modding Tutorials/XML Defs|Defs]]
#** RimWorld uses things called Defs (short for "definitions") like blueprints for in-game objects. Instead of using hidden C# code, RimWorld will look up an XML Def and copy it to the game world. This makes things easier for us, the modders. Everything from characters, animals, floors, damages, buildings, and even diseases in RimWorld use Defs. We're going to make Defs for our Plague Gun and Plague Bullet.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs</small>
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml</small>
#* This file will contain the blueprints (ThingDefs) for our new gun and bullets.
#* Next we will fill out our XML file by copying an existing revolver's ThingDef and a revolver bullet ThingDef.
#* In RimWorld, it is often best to use the XML attribute <code>ParentName="BaseBullet"</code> when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.3]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<uiIconScale>1.4</uiIconScale>
<soundInteract>Interact_Revolver</soundInteract>
<thingSetMakerTags><li>RewardStandardQualitySuper</li></thingSetMakerTags>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<weaponClasses>
<li>RangedLight</li>
</weaponClasses>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# While still in Properties, go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse at the bottom right corner of the window and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun
{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_PlagueBullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
{
}
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing, bool blockedByShield = false)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing, blockedByShield);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:
<br /><nowiki /><small>Languages>English>Keyed</small>
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
</source>
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

== History ==
* This tutorial is a rewrite of the original by Jecrell (see also original forum {{LudeonThread|33219}})

[[Category: Modding tutorials]]
[[Category: Modding]]

Modding Tutorials/Plague Gun

2026-01-05T03:21:23Z

Aelanna: Added editor note.

{{DISPLAYTITLE:Plague Gun}}

This is a tutorial for taking an item [[mod]] from conception all the way to completion, touching on most systems involved in RimWorld modding and explaining each step.

'''Editor Note:''' This tutorial is somewhat obsolete as custom C# code is no longer necessary to apply additional hediffs to the target of a ranged attack, however it has been kept here as it still serves as a useful end-to-end tutorial on how to set up a custom code assembly for a RimWorld mod. This particular version was first written for RimWorld v1.1, but has been updated and should still work in v1.6, if you run into any issues please let us know in in the #mod-development channel of the [https://discord.gg/UTaMDWc RimWorld Discord].

== Introduction ==

In this tutorial we will be using most of the tools available to a Rimworld [[Modding|modder]] to create a custom weapon, known as the Plague Gun.

This weapon will, when its shots hit a living target, have a chance to apply the [[Plague]] hediff ("health difference") to that target.

To do this, we will create XML ThingDefs for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.

This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.

If you have no XML or C# experience, there are good tutorials for XML [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

Make sure to have the following installed, at least one per row:

{| class="wikitable"
|-
| [https://code.visualstudio.com/ VSCode] || A text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

In this stage we will set up the mod and create XML files which add our things to the database.

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a <code>Mods</code> folder (if it doesn't already exist).
<br /><nowiki /><small>RimWorld>Mods>PlagueGun</small>
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About</small>
# Inside the '''About''' folder, make a new text file and rename it About.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>About.xml</small>
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|required items]]. I always make a .txt file first and change it to .xml. If you can't rename your file's type, make sure you have filetypes visible in your operating system's file view settings.
#* [[About.xml]] is the file that shows your mod in the mod list inside the RimWorld game. It is also used when creating a Workshop upload for Steam.
#* At the top of an XML file, always include this for RimWorld. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''Note: the'' version '' tag should always be "1.0". It has no relation with the current RimWorld version.''
#* Then add the MetaData tags for the Workshop and in-game Mod list.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<li>1.1</li>
</supportedVersions>
<description>This mod adds a plague gun, a weapon that has a chance to give your enemies the plague.\n\nFor version 1.1.</description>
</ModMetaData>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>Preview.png</small>
#* This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop.
#* The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb.
#* Example: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs</small>
#* RimWorld will read your XML files in any subdirectory of '''Defs'''. You can name your directories however you like under that folder. Defs>StrangeNewAlienGuns>MyGuns.xml will work. For the purposes of this tutorial, however, we will use the RimWorld standard structure.
#* What are Defs? Main article: [[Modding Tutorials/XML Defs|Defs]]
#** RimWorld uses things called Defs (short for "definitions") like blueprints for in-game objects. Instead of using hidden C# code, RimWorld will look up an XML Def and copy it to the game world. This makes things easier for us, the modders. Everything from characters, animals, floors, damages, buildings, and even diseases in RimWorld use Defs. We're going to make Defs for our Plague Gun and Plague Bullet.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs</small>
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml</small>
#* This file will contain the blueprints (ThingDefs) for our new gun and bullets.
#* Next we will fill out our XML file by copying an existing revolver's ThingDef and a revolver bullet ThingDef.
#* In RimWorld, it is often best to use the XML attribute <code>ParentName="BaseBullet"</code> when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.3]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<uiIconScale>1.4</uiIconScale>
<soundInteract>Interact_Revolver</soundInteract>
<thingSetMakerTags><li>RewardStandardQualitySuper</li></thingSetMakerTags>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<weaponClasses>
<li>RangedLight</li>
</weaponClasses>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# While still in Properties, go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse at the bottom right corner of the window and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun
{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_PlagueBullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
{
}
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing, bool blockedByShield = false)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing, blockedByShield);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:
<br /><nowiki /><small>Languages>English>Keyed</small>
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
</source>
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

== History ==
* This tutorial is a rewrite of the original by Jecrell (see also original forum {{LudeonThread|33219}})

[[Category: Modding tutorials]]
[[Category: Modding]]

Modding Tutorials/ModSettings

2026-01-01T18:43:40Z

Aelanna:

{{BackToTutorials}}

{{:Modding_Tutorials/Outdated}}

Mod settings allow you to offer customisation options to your users.
=Requirements=
* If you still haven't [[Modding Tutorials/Setting up a solution|set up a solution]], what the hell man?
* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]], as that's the entire point of this article.

=What you'll learn=
You'll learn how to write, save and use mod settings.

=Setting up=
Adding mod settings requires two classes, one that inherits from Mod and one that inherits from ModSettings.

=The code=
<source lang="C#">
//inspired by https://gist.github.com/erdelf/84dce0c0a1f00b5836a9d729f845298a
using System.Collections.Generic;
using Verse;
using UnityEngine;

namespace MyExampleMod
{
public class ExampleSettings : ModSettings
{
/// <summary>
/// The three settings our mod has.
/// </summary>
public bool exampleBool;
public float exampleFloat = 200f;
public List<Pawn> exampleListOfPawns = new List<Pawn>();

/// <summary>
/// The part that writes our settings to file. Note that saving is by ref.
/// </summary>
public override void ExposeData()
{
Scribe_Values.Look(ref exampleBool, "exampleBool");
Scribe_Values.Look(ref exampleFloat, "exampleFloat", 200f);
Scribe_Collections.Look(ref exampleListOfPawns, "exampleListOfPawns", LookMode.Reference);
base.ExposeData();
}
}

public class ExampleMod : Mod
{
/// <summary>
/// A reference to our settings.
/// </summary>
ExampleSettings settings;

/// <summary>
/// A mandatory constructor which resolves the reference to our settings.
/// </summary>
/// <param name="content"></param>
public ExampleMod(ModContentPack content) : base(content)
{
this.settings = GetSettings<ExampleSettings>();
}

/// <summary>
/// The (optional) GUI part to set your settings.
/// </summary>
/// <param name="inRect">A Unity Rect with the size of the settings window.</param>
public override void DoSettingsWindowContents(Rect inRect)
{
Listing_Standard listingStandard = new Listing_Standard();
listingStandard.Begin(inRect);
listingStandard.CheckboxLabeled("exampleBoolExplanation", ref settings.exampleBool, "exampleBoolToolTip");
listingStandard.Label("exampleFloatExplanation");
settings.exampleFloat = listingStandard.Slider(settings.exampleFloat, 100f, 300f);
listingStandard.End();
base.DoSettingsWindowContents(inRect);
}

/// <summary>
/// Override SettingsCategory to show up in the list of settings.
/// Using .Translate() is optional, but does allow for localisation.
/// </summary>
/// <returns>The (translated) mod name.</returns>
public override string SettingsCategory()
{
return "MyExampleModName".Translate();
}
}
}
</source>

==ExampleSettings==
===ExposeData===
Writes settings to disk. For more info on saving, see [[Modding Tutorials/ExposeData|ExposeData]].

==ExampleMod==
Refer to the source above for practical information; snippets here are supplemental.
===ExampleSettings===
An easy reference to our settings.
===ExampleMod===
A mandatory constructor.
===DoSettingsWindowContent===
It's not mandatory to implement, but since the point of most settings is the provide customisation to the end user, it makes sense to make them available somehow.
====The GUI====
Listing_Standard is a barebones but useful class for making a GUI, and it does most of the positioning for you. Listing_Standard.Begin and Listing_Standard.End is required: every GUIGroup in Unity you start has to end. If you want more options to Listing_Standard, there's a good [https://github.com/RimWorld-CCL-Reborn/SettingsHelper/wiki SettingsHelper] available.

The Widgets class is a powerful alternative to Listing_Standard that gives you more fine-grained control, at the cost of more effort. You'll have to set the size and position of each Rect manually. You can use [[Modding Tutorials/TweakValue|TweakValues]] to do this more easily.

====Saving====
Saving (altered) settings is done automatically by closing the window. You can optionally override WriteSettings() to add additional functionality to writing settings.
===SettingsCategory===
RimWorld will only make your settings accessible if SettingsCategory returns a string that isn't null or empty.

=Using your settings=
* One easy way to call settings is to make them all static and load their values with ExampleSettings.exampleBool. In certain cases, this is not practical.
* If you can't (or don't want to) make your settings static, you can obtain your settings through the LoadedModManager like so:
LoadedModManager.GetMod<ExampleMod>().GetSettings<ExampleSettings>().exampleBool
* As the above is a lot of code, you can simple add a reference to your settings and resolve it once in a constructor or otherwise.

=On the necessity of HugsLib=
Some people think HugsLib is a necessity for implementing mod settings. This is not true; the above is 100% supported by vanilla, since A17. HugsLib offers an alternative way of using settings.

=See also=
[https://github.com/RimWorld-CCL-Reborn/SettingsHelper/wiki SettingsHelper] - A lightweight MIT-licensed dll with various extension methods for Listing_Standard.<br/>
[https://github.com/UnlimitedHugs/RimworldHugsLib/wiki/Adding-mod-settings HugsLib] - HugsLib is a popular dependency that aims to ease using settings.

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials

2025-12-31T16:27:47Z

Aelanna: /* About RimWorld */

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)
* [[Modding_Tutorials/Code_FloatMenuOptionProvider|FloatMenuOptionProvider]] - How to use <code>FloatMenuOptionProvider</code> to add right click context menu options to arbitrary targets.

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun_(1.1)|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]
* [[Modding Tutorials/Rituals]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Topic:Z4sysmoakgjo1mpw

2025-12-31T16:24:55Z

Aelanna (talk | contribs) commented on "C# Documentation" (Discussing documentation over Mediawiki chat is a bit of a hassle, I rarely look at my messages here, and quite frankly I'm a little conf...)

Modding Tutorials/Setting up a solution

2025-12-07T21:30:13Z

Aelanna: /* .NET Framework via Commmandline */

{{DISPLAYTITLE:Setting Up a Solution}}

{{BackToTutorials}}

In this tutorial you will learn how to set up a solution, along with instructions on setting the output directory and files for more convenient building right into the Assemblies folder.

=Requirements=

* The manual option in this tutorial requires you to have [[Modding_Tutorials/Mod_folder_structure#The Source and Assemblies folders|set up a Source and Assemblies folder]] (the Visual Studio automatic option sets this up for you).
* You will want to have an IDE installed: [[Modding Tutorials/Recommended software#IDE's|Recommended IDE's]].<br/><br/>

=Setting up a solution=
Setting up can be different for different IDE's. Feel free to add '''''complete''''' instructions for your IDE of choice.

===Visual Studio Community 2022===
''NOTE: Visual Studio 2022 is a rather heavy application (2-3 GB for basic functionality) but works out of the box. It is strongly recommended if you are on Windows and have a PC that can handle it. This tutorial is similar for other versions of Visual Studio.''

First, ensure that you have the .NET desktop development workload feature installed. If you didn't select it during installation or if you aren't sure, you can click on Get Tools and Features under the Tools menu to check:

[[File:Get Tools and Feature (VS2022).png|border|To verify that you have the proper module installed, click here.]]

[[File:Workload Selection (VS2022).png|border|Make sure you have the ".NET desktop development" workload installed.]]

==== Option 1 (Manual Method):====
# Create a new class library project
## Once loaded, go to File -> New -> Project...
## Type "Class Library (.NET Framework)" in the search bar, and select the C# option. [[File:ClassLibrary.png|200px|thumb|right|Installing the .NET framework]]
## Enter your project name.
## Choose a location, preferably:<br/><pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## Enter a solution name (optionally, tick "Place solution and project in the same directory")
## Make sure Framework is ".NET Framework 4.7.2"
# In your project, set target framework and various other properties
## In your Solution Explorer (the panel usually located on the right), right click your project -> Properties (or expand your project and double click "Properties" with the wrench icon)
## ''Optional'': Under Application, change your Assembly and Namespace names to anything of your choice
## ''Optional'': You can go to Build -> Advanced... and set "Debugging information" to "Embedded" or "Portable" to remove the extraneous PDB file while also retaining full debug information. You can also set it to "None" to make your DLL smaller, but error stacktraces will have less useful information.
## Leave Advanced..., and set the Output Path to "..\..\Assemblies\" (Or wherever the Assemblies folder is)
# Add references to RimWorld code
## Expand your project in Solution Explorer. Then right click "References" -> Add Reference...
## Click Browse...
## Navigate towards <pre>RimWorldInstallPath/RimWorld******_Data/Managed</pre> and select files: <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre>
## Click "Add"
## Click "OK" to close the Reference Manager.
## Right-click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Using Nuget):====
This option uses [https://www.nuget.org/packages/Krafs.Rimworld.Ref Krafs Rimworld Reference Package] it is less involved than using reference assemblies and is the recommended method.</br>
#Follow the above up till ''Add references to RimWorld code''
#From the Tools menu, select NuGet Package Manager -> Package Manager Settings.
##In the Settings dialog, under Package Management, change the ''Default package management format'' to '''PackageReference'''.
##Click OK to close the dialog.
#Open Nuget Manager and type ''Rimworld''
#Add Krafs Rimworld Reference
You can now continue as if you added the assemblies. Doing this makes your project portable, because RimRef can be downloaded by anyone and used from anywhere, unlike Rimworld's assemblies which can't be distributed.

====Option 3 (Using Rimworld Dotnet Template):====
This option uses [https://github.com/Zeta-of-the-rim/Rimwold-Dotnet-Template Rimworld Dotnet Template] it allows faster creation of mod files including Xml folders</br>

After installing the template.
#Open your mod folder
#create a new folder for your mod (It is best to use the name you want for your mod)
#Open a command prompt in that folder
#type ''dotnet new RimMod'' (This will create a new mod with the name you specified)
#Open the About folder and edit the About.xml file
#Open the .sln file in your preferred IDE
#Add the rimworld assemblies using your preferred method

While this method is faster, it is still good to know how to do it manually.

====Option 4 (Using Cookiecutter):====
This option uses the [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool.</br>
'''Note: despite being automatic and potentially taking away some of the tedium away, the environment it sets up is very particular and this tool is currently not recommended for newcomers.'''</br>
''As of Jan 2019, the cookiecutter is set up for Windows development. Linux/Mac people can still use it, but they will have a few errors to clean up.''</br>
# Open Visual Studio
# Once loaded, go to File -> New -> From Cookiecutter...
# Search for ''rimworld''
# Double-click ''cookiecutter-rimworld-mod-development''
# Change the Template Options:
## ''Create To'' => ''Your/Rimworld/Mod/Directory''
## ''mod_name''
## ''namespace_name'' (don't change if unsure)
## ''author'' => ''your steam username''
## ''target_version'' => current RW version (can leave blank for most up-to-date)
## ''in_game_description'' (not required, can change later in About-Release.xml)
## ''url'' (can leave blank for link to your Steam Workshop profile)
# Click "Create and Open Folder"

===Sharpdevelop===
'''Caution:''' Sharpdevelop (or #develop) does NOT CURRENTLY allow for C# 6.0+ syntax without plugins and does NOT ALLOW for C# 7.0+ syntax at all. For your average project this does not matter, however some existing projects are already built entirely upon C# 6.0+ syntax which can not be compiled anymore in Sharpdevelop. Visual Studio does not have these issues and should be your go-to for compiling large projects such as Combat Extended.

# Create a new class library project in your [[Modding Tutorials/Recommended software#IDE.27s|IDE of choice]];
## Go to File -> New -> Solution;
## Go to C# or .NET -> Library or Class Library (NOT portable);
## Enter a project name (solution name automatically updated);
## Choose a location, preferably:<br/><pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create a directory for solution"/"Create a project within the solution directory",
# In your project, add references to Assembly-CSharp.dll and UnityEngine.dll:
## In your IDE project file browser, right-click the "References" folder and "Add reference";
## Choose the ".NET Assembly Browser" tab and "Browse...";
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre>
## Click "Open" then "OK";
## In the References folder, right-click Assembly-CSharp -> Properties and change "Local copy" to False. Do the same for UnityEngine,
# In your project properties, change the target framework to .NET 4.7.2:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 4.7.2",
# In your project properties, change the build events so only a single file is built:
## Go to the "Compiling" tab, "Output", "Debug info" and choose "No debug information";
## Right-click your .cs files -> Properties and change "Copy to output" (If you haven't resized the properties bar, this will be truncated to "Copy to out") to Never,
# In your project properties, fix the output location to put the DLL in the Assemblies folder:
## Go to the "Compiling" tab, "Output", "Output path" and change the output path to "..\..\Assemblies\".<br/><br/>

===Linux===

On Linux it is possible to develop using .NET packages provided by Microsoft:
# [https://dotnet.microsoft.com/download Install .NET by following the provided instructions.]
# If you use IDE, use it to build (no further details, not tested).
# It is possible to build from CLI using a .csproj file. Find a mod that has description pointing to its GitHub sources and copy from there ([https://github.com/llunak/rimworld-dietfiltersinstorage/blob/master/Source/DietFiltersInStorage.csproj example here]), or use another way to create a .csproj file.
# For building use a command like the following (substitute the proper .csproj file, change Release to Debug for a debug build):<br/><pre>dotnet build <project file>.csproj /property:Configuration=Release</pre>
# If you get errors, possibly the .csproj is Windows-specific and needs to be edited:
## You may need to fix paths (point them to .dll files in RimWorld/RimWorld*_Data/Managed, but it is generally better to use NuGet as described above in Option 2, as that is platform-independent).
## See other setups above for other settings (those IDEs write those settings to the .csproj files).

Note that .NET Framework from Microsoft is Windows-only, and some .csproj files do not build without it. Generally it seems those using Windows-specific paths are affected, while those platform-independent work fine. Either use Mono (see below), or use one that works. The example .csproj file linked above can usually be used as a drop-in replacement, with only properties in the first PropertyGroup needing adjustment. If you really want or need it, you can get .NET Framework from Mono, by additionally doing these steps:
# Install Mono (refer to your distribution's instructions);
# Change the build command to the following (4.7.2 is the .NET version from the .csproj file):<br/><pre>FrameworkPathOverride=$(dirname $(which mono))/../lib/mono/4.7.2-api/ dotnet build <project file>.csproj /property:Configuration=Release</pre>

===Xamarin/MonoDevelop===
The setup is similar as the one above. A few special points to address:
# Mono 4.X isn't backward compatible so you may need to install an older 3.X version of Mono in order to compile against .NET4.7.2 dlls.
# Make sure you uncheck "Use MSBuild build engine (recommended for this project type)" under project > options > build > general (You might find this by right-clicking on your project - not solution - name and selecting options)
# Changing the framework to 4.7.2 can be found (for Linux anyway) in the same place.

More detailed installation instructions for Linux can be found [https://blog.rubenwardy.com/2016/07/21/rimworld-setup-monodevelop/ here] and [https://spdskatr.github.io/RWModdingResources/mono-arch here]. Note that as of now (2021) these may be outdated, so if it doesn't work, you can try the steps described in the Mono section.

===Rider (good for Mac)===
JetBrains Rider is a great cross-platform C# IDE. Previously a paid product (with exceptions), it now offers a community license, making it free for non-commercial use.

# Open Rider and click New Solution in the welcome dialog.
## Click Class Library under .NET on the left. The option may take a second to show up.
## Under Solution Name (and Project Name), enter the name of your mod.
## Set the Solution Directory to [your mod folder]/Source.
## Optionally check "put solution and project in the same directory." This is probably a good idea.
## Change Framework to .Net Framework 4.7.2.
### If you're on Windows and 4.7.2 does not show up as an option, you will have to install the "4.7.2 Dev Pack" from [https://dotnet.microsoft.com/en-us/download/visual-studio-sdks Microsoft].
### If you're on MacOS, you may see an error "mono is not found"; install mono from [https://www.mono-project.com/docs/getting-started/install/mac/ here]. Additionally, if you do not have the option to choose .NET 4.7.2, you can create a project with the available NET option(s) and then manually edit the .csproj file to contain "<TargetFramework>net472</TargetFramework>" later.
## Click Create.
# In the left side bar, expand your solution, right click your project (mod name with "C#" icon) and click Properties.
## In the Properties window, select Configurations > Debug on the left and uncheck Debug Symbols.
## For both configurations, change the Output Path to ../../Assemblies.
## Click OK.
# Expand your project, right click References and click Add Reference.
## Click Add From.
## Browse to the folder with the RimWorld DLLs
### DLL Location for Mac: "/Users/[username]/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Contents/Resources/Data/Managed
### For Win10: "\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed"
## Select both Assembly-CSharp.dll and UnityEngine.dll and click OK.
## Expand Assemblies under References. For both of the assemblies that you just added:
### Right click the assembly and click Properties.
### Uncheck "Copy Local" (you may need to scroll down) and click OK.

You're done! Note that Rider has a built-in decompiler—to view the source of a RimWorld class or method, just right-click its name and click Go To > Definition.

===.NET Framework via Command Line===
If you are on Windows and for some reason you don't want to use Visual Studio, you can also use the C# compiler that comes with the .NET Framework from within the terminal.

# Install the [https://dotnet.microsoft.com .NET Framework].
# (Optional) Adding the compiler to PATH.
## Search for "env" -> Edit system environment variables -> click on "Environment Variables" -> Edit the Path of the user variables -> Add the folder of csc.exe (Usually C:\Windows\Microsoft.NET\Framework\vX.X.XXXXX).
# Find <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre> in your game files(Usualy at: C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\).
# Open a terminal and cd to the location of your .cs file.
# Compile your .cs file (If you skipped adding csc.exe to path, replace it with its full filepath in the following command).
## It should look something like this:<pre>csc.exe /t:library /r:"C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\Assembly-CSharp.dll","C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\UnityEngine.CoreModule.dll" MyMod.cs</pre>
## The command is structured where:<pre>csc.exe</pre> is the compiler(or the whole filepath), and:<pre>/r:"...","..."</pre> is the filepath of both gamefiles from step 3, and:<pre>MyMod.cs</pre> is your C# source code.
# Explanation:
## the /t flag sets it to be a .dll file.
## the /r flag references the game files(Not the decompiled source code, the game files).

===Visual Studio Code via Dev Container===
{{Recode|section=1|reason=Section commented out due to unknown, unvalidated source. Ideally a full guide for VCS needs to be written}}


=Common issues=
* Can't find the option to target .NET Framework 4.7.2? It may require additional installation steps. In Visual Studio, Tools => Get Tools and features => Individual Components => Select ''.NET Framework 4.7.2 development tools'' (or google installation instructions). Also make sure your project is a ''Class Library (.NET '''Framework''')''. Not .NET Core or .NET Standard.

=See also=
* [[Modding Tutorials/Writing custom code|Writing custom code]] continues on setting up your solution.<br/>

[[Category:Modding tutorials]]

Modding Tutorials

2025-12-05T17:59:23Z

Aelanna: Moved "testing mods" guide out of purgatory.

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
{{Stub|section=1|reason= Where does [[Modding Tutorials/Rituals]] fit in the below categories?}}
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)

===Updates and Migrations===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Testing and Troubleshooting===

* [[Modding Tutorials/Testing mods|Testing Mods]] - Tips and tricks for testing mod content

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun_(1.1)|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Testing mods

2025-12-05T17:56:59Z

Aelanna: Complete rewrite.

{{DISPLAYTITLE:Testing Mods}}
{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

This page contains tips and tricks for debugging and testing mod content.

=Development Mode=

''Main Article: [[Development mode]]

Usually referred to as just "dev mode", enabling this option gives you a large number of tools to help test both the vanilla game as well as mod content.

To enable dev mode:

# Start RimWorld
# Go to Options in the Main Menu
# Under Gameplay, check the "Development Mode" box

Development mode will remain on until explicitly turned off, even if you close and reopen the game.

=Debugging=

RimWorld runs on Unity, which uses a modified fork of the Mono runtime. As of RimWorld 1.6 (Odyssey), the current versions are:

* Unity 2022.3.35 (https://unity.com/releases/editor/whats-new/2022.3.35f1)
* Mono (https://github.com/Unity-Technologies/mono/tree/unity-2022.3-mbe)

If you are using [[Modding_Tutorials/Recommended_software|Rider]], the easiest way to set up debugging for custom assemblies is to use Gareth's RimWorld plugin: https://plugins.jetbrains.com/plugin/21583-rimworld-development-environment

If you are not using Rider or do not want to use the plugin, there are instructions for setting up Doorstop manually here: https://github.com/pardeike/Rimworld-Doorstop

=Tips=

The following are specific tips for testing various types of mod content:

==Weapons and Apparel==

You can spawn weapons and apparel by using the "Spawn weapon" and "Spawn apparel" dev mode debug commands, respectively.

There are also debug output commands for showing the chance of spawning any given weapon or apparel piece, to help diagnose whether your tags are correctly configured.

==Pawns==

You can test custom pawns by using the "Spawn pawn" dev mode command. This will list out all PawnKindDefs in the game.

==Incidents==

You can use the Incident dev mode commands to test various incidents, including raids.

==Jobs==

"Toggle job logging" and "Draw pawn debug" can be helpful for diagnosing pawn AI.

==Lords==

Lords are group AI controllers used by everything from trade caravans to raiding parties.

* View settings -> Draw Duties (for seeing what each pawn does)
* View settings -> Draw Lords (for seeing what the Lord does)
* View settings -> Log Lord Toil Transitions (for reading what transitions happen)

=Quicktest=

When dev mode is enabled, there will be a Quicktest option on the Main Menu that instantly loads into a Crashlanded map with all default options.

You can also have the game load instantly into a Quicktest map on load by using the <code>-quicktest</code> command line argument:

<source>
C:/Path/To/Game/RimWorld.exe -quicktest
</source>

On Mac:

<source>
/Users/Username/Library/Application\ Support/Steam/SteamApps/common/RimWorld/RimWorldMac.app/Contents/MacOS/RimWorldMac -quicktest
</source>

You can make a shortcut to the game with this command line argument.

Alternatively, if you have a save file named <code>autostart.rws</code>, then game will load that on start.

=Save Data=

You can override the save data folder using the <code>-savedatafolder</code> command line argument. This is useful if you want to install the game on a USB drive so you can plug and play it from anywhere:

<source>
C:/Path/To/Game/RimWorld.exe -savedatafolder=C:/Path/To/The/Folder
</source>

You can also use relative file paths:

<source>
-savedatafolder=SaveData
</source>

Be sure the game is running with permission to modify the folder; it may not work properly if you run the game under default permissions on its own install folder.

You can combine the -savedatafolder with the -quicktest argument for a clean modding environment.

=Mod Tools=

* [https://github.com/Jaxe-Dev/PublisherPlus Publisher Plus by Jaxe] ([https://steamcommunity.com/sharedfiles/filedetails/?id=1510554297 Steam Workshop]) - Gives you more options when uploading a mod to Steam Workshop, including excluding files or folders from the upload.

[[Category:Modding tutorials]]

Modding Tutorials/Plague Gun

2025-11-22T16:59:37Z

Aelanna: /* C# Workspace Setup */

This is a tutorial for taking an item [[mod]] from conception all the way to completion, touching on most systems involved in RimWorld modding and explaining each step.

== Introduction ==

In this tutorial we will be using most of the tools available to a Rimworld [[Modding|modder]] to create a custom weapon, known as the Plague Gun.

This weapon will, when its shots hit a living target, have a chance to apply the [[Plague]] hediff ("health difference") to that target.

To do this, we will create XML ThingDefs for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.

This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.

If you have no XML or C# experience, there are good tutorials for XML [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

Make sure to have the following installed, at least one per row:

{| class="wikitable"
|-
| [https://code.visualstudio.com/ VSCode] || A text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

In this stage we will set up the mod and create XML files which add our things to the database.

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a <code>Mods</code> folder (if it doesn't already exist).
<br /><nowiki /><small>RimWorld>Mods>PlagueGun</small>
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About</small>
# Inside the '''About''' folder, make a new text file and rename it About.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>About.xml</small>
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|required items]]. I always make a .txt file first and change it to .xml. If you can't rename your file's type, make sure you have filetypes visible in your operating system's file view settings.
#* [[About.xml]] is the file that shows your mod in the mod list inside the RimWorld game. It is also used when creating a Workshop upload for Steam.
#* At the top of an XML file, always include this for RimWorld. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''Note: the'' version '' tag should always be "1.0". It has no relation with the current RimWorld version.''
#* Then add the MetaData tags for the Workshop and in-game Mod list.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<li>1.1</li>
</supportedVersions>
<description>This mod adds a plague gun, a weapon that has a chance to give your enemies the plague.\n\nFor version 1.1.</description>
</ModMetaData>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>Preview.png</small>
#* This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop.
#* The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb.
#* Example: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs</small>
#* RimWorld will read your XML files in any subdirectory of '''Defs'''. You can name your directories however you like under that folder. Defs>StrangeNewAlienGuns>MyGuns.xml will work. For the purposes of this tutorial, however, we will use the RimWorld standard structure.
#* What are Defs? Main article: [[Modding Tutorials/XML Defs|Defs]]
#** RimWorld uses things called Defs (short for "definitions") like blueprints for in-game objects. Instead of using hidden C# code, RimWorld will look up an XML Def and copy it to the game world. This makes things easier for us, the modders. Everything from characters, animals, floors, damages, buildings, and even diseases in RimWorld use Defs. We're going to make Defs for our Plague Gun and Plague Bullet.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs</small>
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml</small>
#* This file will contain the blueprints (ThingDefs) for our new gun and bullets.
#* Next we will fill out our XML file by copying an existing revolver's ThingDef and a revolver bullet ThingDef.
#* In RimWorld, it is often best to use the XML attribute <code>ParentName="BaseBullet"</code> when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.3]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<uiIconScale>1.4</uiIconScale>
<soundInteract>Interact_Revolver</soundInteract>
<thingSetMakerTags><li>RewardStandardQualitySuper</li></thingSetMakerTags>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<weaponClasses>
<li>RangedLight</li>
</weaponClasses>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# While still in Properties, go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse at the bottom right corner of the window and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun
{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_PlagueBullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
{
}
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing, bool blockedByShield = false)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing, blockedByShield);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:
<br /><nowiki /><small>Languages>English>Keyed</small>
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
</source>
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

== History ==
* This tutorial is a rewrite of the original by Jecrell (see also original forum {{LudeonThread|33219}})

[[Category: Modding tutorials]]
[[Category: Modding]]

Modding Tutorials/Plague Gun

2025-11-22T16:58:32Z

Aelanna: /* C# Workspace Setup */

This is a tutorial for taking an item [[mod]] from conception all the way to completion, touching on most systems involved in RimWorld modding and explaining each step.

== Introduction ==

In this tutorial we will be using most of the tools available to a Rimworld [[Modding|modder]] to create a custom weapon, known as the Plague Gun.

This weapon will, when its shots hit a living target, have a chance to apply the [[Plague]] hediff ("health difference") to that target.

To do this, we will create XML ThingDefs for the gun and projectile, create a C# assembly which determines what happens when the projectile hits a target, and link that behavior back to the XML.

This tutorial will assume a basic familiarity with XML and C# syntax. It should be simple enough to follow if you're only a beginner.

If you have no XML or C# experience, there are good tutorials for XML [https://www.w3schools.com/xml/ here] and C# [https://www.learncs.org/ here].

=== The Completed Mod ===
For a working example, check out [https://github.com/dninemfive/PlagueGun this GitHub repo].

== Required Items ==

Make sure to have the following installed, at least one per row:

{| class="wikitable"
|-
| [https://code.visualstudio.com/ VSCode] || A text editor that allows you to edit XML files and use "Find in Files" for referencing.
|-
| [https://visualstudio.microsoft.com/vs/community/ Visual Studio Community] || Use this or any other C# compiler to turn scripts into .dll files that RimWorld can use.
|-
| [https://github.com/icsharpcode/ILSpy/releases ILSpy]|| This is for referencing the game's decompiled C# scripts.
|}

For more detailed recommendations, see [[Modding Tutorials/Recommended software|here]].

== XML Stage ==

In this stage we will set up the mod and create XML files which add our things to the database.

# Locate your RimWorld folder.
#* On Steam, you can find it by right-clicking the game in your games list > Properties > Local Files > Browse Local Files...
#** By default, it will be located at <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld</code> if you bought it through Steam on Windows.
#* If you bought the DRM-free version, it will be located wherever you unzipped it.
#* On GOG, you can find it by right-clicking the game in your games list > Manage Installation > Show Folder
#** By default it will be located at <code>C:\Program Files (x86)\GOG Galaxy\Games\RimWorld</code> if you bought it through GOG on Windows.
# Create a <code>Mods</code> folder (if it doesn't already exist).
<br /><nowiki /><small>RimWorld>Mods>PlagueGun</small>
#* Go into the Mods folder.
#* Make a new folder with our mod's title: '''PlagueGun'''
# Inside '''PlagueGun''', make an '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About</small>
# Inside the '''About''' folder, make a new text file and rename it About.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>About.xml</small>
#* You will need a good text editor to make a proper XML file -- see [[#Required Items|required items]]. I always make a .txt file first and change it to .xml. If you can't rename your file's type, make sure you have filetypes visible in your operating system's file view settings.
#* [[About.xml]] is the file that shows your mod in the mod list inside the RimWorld game. It is also used when creating a Workshop upload for Steam.
#* At the top of an XML file, always include this for RimWorld. It basically just gives the game some info about how to read the file. <source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source> ''Note: the'' version '' tag should always be "1.0". It has no relation with the current RimWorld version.''
#* Then add the MetaData tags for the Workshop and in-game Mod list.<source lang ="xml"><ModMetaData>
<name>Test Mod - Plague Gun</name> 
<author>YourNameHere</author>
<packageId>YourNameHere.PlagueGun</packageId> 
<supportedVersions> 
<li>1.1</li>
</supportedVersions>
<description>This mod adds a plague gun, a weapon that has a chance to give your enemies the plague.\n\nFor version 1.1.</description>
</ModMetaData>
</source>
#* Save the file.
# Add a Preview.png or Preview.jpeg to your '''About''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>About>Preview.png</small>
#* This lets users see what your mod looks like in the RimWorld mod list or on the Steam Workshop.
#* The conventional dimensions to fit the preview image on Steam are 640x360. The image must be smaller than 1mb.
#* Example: [[File:Preview.png]]
# Make a '''Defs''' folder in your Mod's directory.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs</small>
#* RimWorld will read your XML files in any subdirectory of '''Defs'''. You can name your directories however you like under that folder. Defs>StrangeNewAlienGuns>MyGuns.xml will work. For the purposes of this tutorial, however, we will use the RimWorld standard structure.
#* What are Defs? Main article: [[Modding Tutorials/XML Defs|Defs]]
#** RimWorld uses things called Defs (short for "definitions") like blueprints for in-game objects. Instead of using hidden C# code, RimWorld will look up an XML Def and copy it to the game world. This makes things easier for us, the modders. Everything from characters, animals, floors, damages, buildings, and even diseases in RimWorld use Defs. We're going to make Defs for our Plague Gun and Plague Bullet.
# Make a new '''ThingDefs''' folder in your '''Defs''' folder.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs</small>
# Make a new text file in your '''ThingDefs''' folder, and change it to RangedWeapon_PlagueGun.xml.
<br /><nowiki /><small>RimWorld>Mods>PlagueGun>Defs>ThingDefs>RangedWeapon_PlagueGun.xml</small>
#* This file will contain the blueprints (ThingDefs) for our new gun and bullets.
#* Next we will fill out our XML file by copying an existing revolver's ThingDef and a revolver bullet ThingDef.
#* In RimWorld, it is often best to use the XML attribute <code>ParentName="BaseBullet"</code> when making a bullet, because it will copy XML code from a pre-existing BaseBullet ThingDef, which can save us time and key taps. Main article: [[Modding Tutorials/XML file structure#Inheritance|Inheritance]]
# First, add our favourite line to the top.<source lang = "xml"><?xml version="1.0" encoding="utf-8"?></source>
# Add the <code><Defs></code> opening and closing tags to the XML to hold our new code.<source lang = "xml>
<?xml version="1.0" encoding="utf-8"?>
<Defs>

</Defs>
</source>
# Use your text editor. Use its "Find in Files" function to reference and copy Bullet_Revolver to your XML file.
#* Find in Files is one of my most-used functions. In Notepad++, if you press CTRL+SHIFT+F, you can go to the Find in Files screen. From there, you can enter a phrase to search for, and then you can enter the file path to search through. This makes it wildly easier to search for examples in RimWorld's Core. RimWorld holds copies of all of its weapons, items, buildings, etc. inside the Mods/Core directory.
#* So, start by using Find in Files... and find this: <code>defName>Bullet_Revolver</code>
#* When you find Bullet_Revolver, copy from its beginning <code><ThingDef></code> all the way until its closing <code></ThingDef></code> tag into your XML File.
# Use your text editor's "Find in Files" function to reference and copy Gun_Revolver to your XML file.
#* Typically, Gun_Revolver is right below Bullet_Revolver in XML, so hopefully this will be easy to find and copy.
#* Again, copy the ThingDef block to your new XML file.
# Change the defName, labels, and other stats of Bullet_Revolver and Revolver in your XML file to make them unique.
#* '''A word on defNames:''' <code>defName</code>s are how the game references defs anywhere they're used in XML, since they're unique. When telling your plague gun to fire plague bullets, for instance, set its <code>defaultProjectile</code> to your projectile's defName, like so:<source lang ="xml"><defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile></source>
#* '''TIP:''' Use prefixes to avoid conflicting with other mods. RimWorld will overwrite any def with <code><defName>Tobacco</defName></code>, for instance, if it finds another with the same defName. If two modders use different prefixes, however, e.g. <code><defName>VGP_Tobacco</defName></code> and <code><defName>ROM_Tobacco</defName></code>, no conflict will occur, and both mods can co-exist. This tutorial uses TST_ for its example prefix. Main article: [[Modding_Tutorials/Compatibility|Compatibility]]
#* By contrast, labels, descriptions, and other non-defName tags can generally be non-unique without a risk of conflicts, except perhaps confusion for the end user.

<big>'''If all you were interested in is making a gun mod, you are done.'''</big> You'll of course want to edit values like the damage it does, and [[Modding_Tutorials/Testing_mods|test your mod]]. You'll also want to change the <code>texturePath</code> to your unique art, and whatever else.

=== Completed Example ===

''Note'': The example is up-to-date for [[Version|1.3]] and will likely be outdated in the future. The above steps should always be relevant.
<source lang ="xml">
<?xml version="1.0" encoding="utf-8" ?>
<Defs>
<ThingDef ParentName="BaseBullet">
<defName>TST_Bullet_PlagueGun</defName>
<label>plague bullet</label>
<graphicData>
<texPath>Things/Projectile/Bullet_Small</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<projectile>
<damageDef>Bullet</damageDef>
<damageAmountBase>12</damageAmountBase>
<stoppingPower>1</stoppingPower>
<speed>55</speed>
</projectile>
</ThingDef>

<ThingDef ParentName="BaseHumanMakeableGun">
<defName>TST_Gun_PlagueGun</defName>
<label>plague gun</label>
<description>A curious weapon notable for its horrible health effects.</description>
<graphicData>
<texPath>Things/Item/Equipment/WeaponRanged/Revolver</texPath>
<graphicClass>Graphic_Single</graphicClass>
</graphicData>
<uiIconScale>1.4</uiIconScale>
<soundInteract>Interact_Revolver</soundInteract>
<thingSetMakerTags><li>RewardStandardQualitySuper</li></thingSetMakerTags>
<statBases>
<WorkToMake>4000</WorkToMake>
<Mass>1.4</Mass>
<AccuracyTouch>0.80</AccuracyTouch>
<AccuracyShort>0.75</AccuracyShort>
<AccuracyMedium>0.45</AccuracyMedium>
<AccuracyLong>0.35</AccuracyLong>
<RangedWeapon_Cooldown>1.6</RangedWeapon_Cooldown>
</statBases>
<weaponTags>
<li>SimpleGun</li>
<li>Revolver</li>
</weaponTags>
<weaponClasses>
<li>RangedLight</li>
</weaponClasses>
<costList>
<Steel>30</Steel>
<ComponentIndustrial>2</ComponentIndustrial>
</costList>
<recipeMaker>
<skillRequirements>
<Crafting>3</Crafting>
</skillRequirements>
</recipeMaker>
<verbs>
<li>
<verbClass>Verb_Shoot</verbClass>
<hasStandardCommand>true</hasStandardCommand>
<defaultProjectile>TST_Bullet_PlagueGun</defaultProjectile>
<warmupTime>0.3</warmupTime>
<range>25.9</range>
<soundCast>Shot_Revolver</soundCast>
<soundCastTail>GunTail_Light</soundCastTail>
<muzzleFlashScale>9</muzzleFlashScale>
</li>
</verbs>
<tools>
<li>
<label>grip</label>
<capacities>
<li>Blunt</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
<li>
<label>barrel</label>
<capacities>
<li>Blunt</li>
<li>Poke</li>
</capacities>
<power>9</power>
<cooldownTime>2</cooldownTime>
</li>
</tools>
</ThingDef>
</Defs>
</source>

== C# Workspace Setup ==
{{Main|Modding Tutorials/Setting up a solution}}

Next, we will set up a workspace to write C# code, which is a little bit more involved than just using a text editor.

# Open your compiler of choice for C#.
#* This tutorial will assume you're using Visual Studio Community Edition, a free Windows-based compiler for C# code.
# Make a new Visual C# Class Library .NET Framework project. Name it PlagueGun. Make its directory RimWorld>Mods>PlagueGun>Source
#* File → New → Project → Class Library (.NET Framework).
#* Don't get this confused with "Class Library (.NET Standard)" or "Class Library (.NET Core)"!
# Go into the project properties.
#* Project → PlagueGun Properties.
# In that window, change the Target Framework version to .NET Framework 4.7.2
#* Forgetting to do this will cause lots of errors.
#* Select Yes when it asks you if you're sure to change the framework.
# While still in Properties, go to the '''Build''' tab.
# Change the output path to be RimWorld\Mods\PlagueGun\Assemblies
#* All .dll files will go into this directory when we "build" our code library.
# In that same window, click the Advanced... button.
# In Solution Explorer. Go into Properties and edit AssemblyInfo.cs. Change the name of your assembly and assembly file version number as you like.
#* This doesn't have to all be the same as your namespace, but it doesn't hurt to be consistent.
# In the main option bar at the top of the visual studio (File, Edit, View...), click Project, and click Add Reference.
# Click Browse at the bottom right corner of the window and go to RimWorld\RimWorldWin64_Data\Managed
# Add references to Assembly-CSharp.dll, UnityEngine.dll, and UnityEngine.CoreModule.dll.
#* In 1.1 the Unity DLLs were split up and are no longer all contained in the same module.
#* For our purposes we only need UnityEngine.CoreModule.dll, as it contains some code we will use later.
#* In general, it's also a good idea to add UnityEngine.dll, which allows Visual Studio to tell you which modules you're missing if you get related errors.
# In the Solution Explorer (typically on the right side of the application), look at the references drop down list.
# Select Assembly-CSharp. Check the Properties section (usually under Solution Explorer). Make sure the properties section has Copy Local set to FALSE.
# Do this (Copy Local to FALSE) for UnityEngine and UnityEngine.CoreModule as well.
#* By doing this, we prevent the project from causing one million hash conflicts by copying the entire game's code twice!

Now the workspace setup is complete and we can add C# code to RimWorld.

'''Note:''' Exact folder names might differ between installs. The naming scheme differs slightly between the DRM-free and Steam version of the mod.

== C# Coding ==

Now let's start writing the code we'll need to add custom behavior to our projectiles.

=== Getting Started ===
# Open Class1.cs in the sidebar, usually on the right in Visual Studio.
# Right-click and rename the .cs file to your liking.
# Add these lines to the top this file (and every .cs file you make from now on for modding RimWorld).<source lang ="csharp">
using RimWorld;
using Verse;
</source>
#* These tell the code you're working with RimWorld. Without these, our code will not be able to understand references to RimWorld code.
# Add a namespace line. By default, this is your project name. Take note - you will need this to connect to XML later.<source lang="csharp">
namespace TST_PlagueGun
{
}
</source>
#* '''Note:''' ''Using a prefix on the namespace is not required, but it's good for consistency and in the rare case they may overlap - such as when multiple people follow the same tutorial to learn how to mod.''

=== Connecting XML and C#, Part 1 ===
{{Main|Modding Tutorials/DefModExtension}}

# First, let's add a way to read XML data into your assembly.
# Rename public class Class1 to ModExtension_PlagueBullet and make it inherit DefModExtension. As a reminder, inheritance looks like this:<source lang="csharp">
public class ModExtension_PlagueBullet : DefModExtension
{
}
</source>
#* '''Note:''' Renaming things in an IDE like Visual Studio is best done by pressing F2 or right-clicking the item/name. Doing it like that will change all occurrences of that thing, so everything that references your namespace or Class1 will now use the new name.
# Add the following fields in ModExtension_PlagueBullet:<source lang="csharp">
public float addHediffChance = 0.05f;
public HediffDef hediffToAdd;
</source>
#* Here, we're giving the field addHediffChance a default value, which means it doesn't need to be set explicitly in XML.
#* '''Note:''' Standard modding practice is to give fields exposed to XML camelCase names, for consistency with vanilla XML.
# Now let's add the XML which connects to this ModExtension. In your TST_Bullet_PlagueGun def, add the following lines: <source lang="XML">
<modExtensions>
<li Class="TST_PlagueGun.ModExtension_PlagueBullet">
<addHediffChance>0.05</addHediffChance>
<hediffToAdd>Plague</hediffToAdd>
</li>
</modExtensions>
</source>
#* '''Note:''' Note the XML tags match the names of the fields in the C# class. This allows the XML to provide data to the program. When the mod is loaded, the XML will be read, and used to fill in the corresponding fields.
#* Additionally, take care to note you can set the value of addHediffChance to any valid floating point number and it will be reflected in-game. The value given in C# is only the default value if unset.

=== Writing the Projectile ===
# Let's make the actual projectile. For this tutorial, we're going to make a new projectile that checks for impact and adds a Hediff (health differential - poison, toxins, implants, anything).
# First, create a new .cs file by right-clicking the PlagueGun part of the Solution Explorer and selecting Add > New Item.
#* '''Note:''' in C#, you can have multiple class definitions in a single file. We're just making a new file for organizational purposes.
# Make your new class inherit the Bullet class (a child of the Projectile class), so the game will treat your new projectile like a bullet and not throw (fun) errors. <source lang="csharp">
public class Projectile_PlagueBullet : Bullet
</source>
# First, let's connect our new projectile to the relevant ModExtension: <source lang="csharp">
public ModExtension_PlagueBullet Props => def.GetModExtension<ModExtension_PlagueBullet>();
</source>
#* This line is a Property, basically a method which doesn't take any arguments, and can generally speaking be treated as a variable. See [https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/properties this article] for more details.
# Now, let's start the actual core code of this mod. Let's begin by overriding the Impact method on the base Bullet class, like so: <source lang="csharp">
protected override void Impact(Thing hitThing, bool blockedByShield = false)
</source>
#* The <code>override</code> keyword tells the compiler that we're replacing the functionality of the <code>Impact</code> method from the <code>Bullet</code> class we're inheriting from.
# First, let's call the base version of this method so we don't need to rewrite all the logic about damaging a pawn - we only care about adding the hediff ''after'' damage occurs. <source lang="csharp">
base.Impact(hitThing, blockedByShield);
</source>
# Next, we check to make sure the ModExtension was properly loaded, that we hit something, and that what we hit was a [[Pawns|Pawn]].<source lang="csharp">
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
</source>
#* '''Note:''' Null checking is a very important skill, especially for Rimworld modding. If you ever get a <code>NullReferenceException</code>, check to make sure you're correctly handling null values.
#* Also, note that we initialize a <code>Pawn</code> version of the <code>hitThing</code> while checking its type; we'll use this later. This statement ''also'' null-checks this new variable, in case you were wondering.
# Now that we know we hit a pawn, we generate a random number to see whether to apply the hediff.<source lang="csharp">
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
</source>
#* <code>Rand</code> is the base game's randomness generation class. <code>Value</code> grabs the next random number between 0 and 1 and updates the class.
# If a hediff is applied, we want to alert the player, so we create a message in the top-left of the screen.<source lang="csharp">
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
</source>
# Before adding the hediff, we need to check if the pawn already has it, so we get the hediff from the pawn, if it exists.<source lang="csharp">
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
</source>
#* '''Note:''' The <code>?.</code> is called the [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/member-access-operators#null-conditional-operators--and- null conditional operator]. It's basically an in-line null check; if the hit pawn's health tracker (<code>health</code>) or hediff set (<code>hediffSet</code>) are null it sets <code>plagueOnPawn</code> to null instead of throwing an error.
# Now we finally add the hediff. If the pawn already has the plague we just increase its severity; otherwise, we create and add a new hediff with a random severity.<source lang="csharp">
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}</source>

==== Whew. ====
Let's take a break and recap for a second. If you've followed the projectile section so far, this is the code you should have in your new .cs file:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
}
}
}
}
</source>
Don't worry, we're almost finished. In fact, if you compile right now the gun ''will'' work - there just won't be any feedback if the shooter misses. This might be desirable, but let's add some feedback anyway.

Well, that's a little bit of a lie. You'd also need to add the <code><thingClass></code> node to the XML, given below.

We want to add an <code>else</code> block to our <code>if (rand <= Props.addHediffChance))</code> statement. This is where keeping track of curly braces comes in; Visual Studio should draw vertical lines between the correct curlies. Add this:<source lang="csharp">
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
</source>
* This throws a mote (particle effect, essentially), with text stating that the plague was not applied, at the target's position.
* Fun fact: the <code>.ToVector3()</code> call is the entire reason we needed to reference UnityEngine and UnityEngine.CoreModule.

=== Connecting XML and C#, Part 2 ===
Finally, we need to make sure our projectile's def tells the game to use our new Projectile_PlagueBullet class instead of Bullet.<source lang="xml">
<thingClass>TST_PlagueGun.Projectile_PlagueBullet</thingClass>
</source>

We're done! Your final Projectile_PlagueBullet class should look like this:<source lang="csharp">
using Verse;
using RimWorld;

namespace TST_PlagueGun
{
public class Projectile_PlagueBullet : Bullet
{
public ModExtension_PlagueBullet Props => base.def.GetModExtension<ModExtension_PlagueBullet>();

protected override void Impact(Thing hitThing, bool blockedByShield = false)
{
base.Impact(hitThing, blockedByShield);
if (Props != null && hitThing != null && hitThing is Pawn hitPawn)
{
float rand = Rand.Value;
if (rand <= Props.addHediffChance)
{
Messages.Message("TST_PlagueBullet_SuccessMessage".Translate(
this.launcher.Label, hitPawn.Label
), MessageTypeDefOf.NeutralEvent);
Hediff plagueOnPawn = hitPawn.health?.hediffSet?.GetFirstHediffOfDef(Props.hediffToAdd);
float randomSeverity = Rand.Range(0.15f, 0.30f);
if (plagueOnPawn != null)
{
plagueOnPawn.Severity += randomSeverity;
}
else
{
Hediff hediff = HediffMaker.MakeHediff(Props.hediffToAdd, hitPawn);
hediff.Severity = randomSeverity;
hitPawn.health.AddHediff(hediff);
}
}
else
{
MoteMaker.ThrowText(hitThing.PositionHeld.ToVector3(), hitThing.MapHeld, "TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance), 12f);
}
}
}
}
}</source>

Just compile and test your work; the plague will be properly applied and everything.

'''Note:''' Code you write on your own should not look like this - for one thing, it should be well-commented so that others (even if it's just you in the future) know exactly what you're trying to do and how you're doing it. The code [https://github.com/dninemfive/PlagueGun/blob/master/PlagueGun/Projectile_PlagueBullet.cs in the repo] is probably over-commented and designed for a general audience but I recommend reviewing it.

== Localization ==
...well, almost. If you did test the gun just now, you'll have seen that the text was all distorted, using special characters which looked like the normal ones instead of text you expected. This is because of the use of <code>.Translate()</code> on keys which do not have translations in the language database. We just need to add those, and we'll be all set!

# First, create a bunch of folders, starting in the root of your mod folder:
<br /><nowiki /><small>Languages>English>Keyed</small>
# Next, create a new file called PlagueGun_Keys.xml, with our favorite header.<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
</source>
# This will be really quick. Add the opening and closing <code><LanguageData></code> tags:<source lang="xml">
<LanguageData>
</LanguageData>
</source>
# And, finally, add translations for the two keys used in the projectile class.<source lang="xml">
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</source>
#* The <code>{0}</code> and <code>{1}</code> in these keys will be replaced with the first and second arguments, respectively, of the <code>.Translate()</code> calls. For reference:<source lang="csharp">
// successful hit message
"TST_PlagueBullet_SuccessMessage".Translate(this.launcher.Label, hitPawn.Label)
// unsuccessful hit mote
"TST_PlagueBullet_FailureMote".Translate(Props.addHediffChance)
</source>
#* If you give <code>.Translate()</code> more arguments, you can use <code>{2}</code>, <code>{3}</code>, &c.
#* Note that, since you only passed one argument to the failure message, <code>{1}</code> would not be replaced with anything.
# Your PlagueGun_Keys.xml file should look like this:<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<LanguageData>
<TST_PlagueBullet_FailureMote>Failure: {0} chance</TST_PlagueBullet_FailureMote>
<TST_PlagueBullet_SuccessMessage>{0} infected {1} with the plague!</TST_PlagueBullet_SuccessMessage>
</LanguageData>
</source>

== Next Steps ==
This concludes this tutorial. Congratulations on making it this far; you now have a solid understanding of XML and C# modding, and of connecting these two. There's a lot more to learn, especially on the C# end, so make sure to practice. If you have any questions don't hesitate to hit up the [https://discord.gg/UTaMDWc Discord]#mod-development or the [https://ludeon.com/forums/index.php?board=14.0 forums] for help.

As for this mod, you might want to add custom textures or sounds. For your next, you might want to try messing around with [[Modding Tutorials/Harmony|Harmony]] or see other [[Modding Tutorials|tutorials]] for inspiration.

== See also ==
* [[Modding Tutorials/Setting up a solution|Setting up a solution]]
* [[Modding Tutorials/Distribution|Distribution]]
* [[Modding Tutorials/Harmony|Harmony]]
* [[Modding_Tutorials/Mod_folder_structure#The_Languages_folder|Language support]]

== History ==
* This tutorial is a rewrite of the original by Jecrell (see also original forum {{LudeonThread|33219}})

[[Category: Modding tutorials]]
[[Category: Modding]]

Modding Tutorials/Setting up a solution

2025-11-22T16:47:18Z

Aelanna: /* Option 1 (Manual Method): */

{{DISPLAYTITLE:Setting Up a Solution}}

{{BackToTutorials}}

In this tutorial you will learn how to set up a solution, along with instructions on setting the output directory and files for more convenient building right into the Assemblies folder.

=Requirements=

* The manual option in this tutorial requires you to have [[Modding_Tutorials/Mod_folder_structure#The Source and Assemblies folders|set up a Source and Assemblies folder]] (the Visual Studio automatic option sets this up for you).
* You will want to have an IDE installed: [[Modding Tutorials/Recommended software#IDE's|Recommended IDE's]].<br/><br/>

=Setting up a solution=
Setting up can be different for different IDE's. Feel free to add '''''complete''''' instructions for your IDE of choice.

===Visual Studio Community 2022===
''NOTE: Visual Studio 2022 is a rather heavy application (2-3 GB for basic functionality) but works out of the box. It is strongly recommended if you are on Windows and have a PC that can handle it. This tutorial is similar for other versions of Visual Studio.''

First, ensure that you have the .NET desktop development workload feature installed. If you didn't select it during installation or if you aren't sure, you can click on Get Tools and Features under the Tools menu to check:

[[File:Get Tools and Feature (VS2022).png|border|To verify that you have the proper module installed, click here.]]

[[File:Workload Selection (VS2022).png|border|Make sure you have the ".NET desktop development" workload installed.]]

==== Option 1 (Manual Method):====
# Create a new class library project
## Once loaded, go to File -> New -> Project...
## Type "Class Library (.NET Framework)" in the search bar, and select the C# option. [[File:ClassLibrary.png|200px|thumb|right|Installing the .NET framework]]
## Enter your project name.
## Choose a location, preferably:<br/><pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## Enter a solution name (optionally, tick "Place solution and project in the same directory")
## Make sure Framework is ".NET Framework 4.7.2"
# In your project, set target framework and various other properties
## In your Solution Explorer (the panel usually located on the right), right click your project -> Properties (or expand your project and double click "Properties" with the wrench icon)
## ''Optional'': Under Application, change your Assembly and Namespace names to anything of your choice
## ''Optional'': You can go to Build -> Advanced... and set "Debugging information" to "Embedded" or "Portable" to remove the extraneous PDB file while also retaining full debug information. You can also set it to "None" to make your DLL smaller, but error stacktraces will have less useful information.
## Leave Advanced..., and set the Output Path to "..\..\Assemblies\" (Or wherever the Assemblies folder is)
# Add references to RimWorld code
## Expand your project in Solution Explorer. Then right click "References" -> Add Reference...
## Click Browse...
## Navigate towards <pre>RimWorldInstallPath/RimWorld******_Data/Managed</pre> and select files: <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre>
## Click "Add"
## Click "OK" to close the Reference Manager.
## Right-click on both Assembly-CSharp.dll and UnityEngine.dll and set Copy Local to False (Properties pane).

====Option 2 (Using Nuget):====
This option uses [https://www.nuget.org/packages/Krafs.Rimworld.Ref Krafs Rimworld Reference Package] it is less involved than using reference assemblies and is the recommended method.</br>
#Follow the above up till ''Add references to RimWorld code''
#From the Tools menu, select NuGet Package Manager -> Package Manager Settings.
##In the Settings dialog, under Package Management, change the ''Default package management format'' to '''PackageReference'''.
##Click OK to close the dialog.
#Open Nuget Manager and type ''Rimworld''
#Add Krafs Rimworld Reference
You can now continue as if you added the assemblies. Doing this makes your project portable, because RimRef can be downloaded by anyone and used from anywhere, unlike Rimworld's assemblies which can't be distributed.

====Option 3 (Using Rimworld Dotnet Template):====
This option uses [https://github.com/Zeta-of-the-rim/Rimwold-Dotnet-Template Rimworld Dotnet Template] it allows faster creation of mod files including Xml folders</br>

After installing the template.
#Open your mod folder
#create a new folder for your mod (It is best to use the name you want for your mod)
#Open a command prompt in that folder
#type ''dotnet new RimMod'' (This will create a new mod with the name you specified)
#Open the About folder and edit the About.xml file
#Open the .sln file in your preferred IDE
#Add the rimworld assemblies using your preferred method

While this method is faster, it is still good to know how to do it manually.

====Option 4 (Using Cookiecutter):====
This option uses the [https://ludeon.com/forums/index.php?topic=39038.0 Rimworld Mod Development Cookiecutter] tool.</br>
'''Note: despite being automatic and potentially taking away some of the tedium away, the environment it sets up is very particular and this tool is currently not recommended for newcomers.'''</br>
''As of Jan 2019, the cookiecutter is set up for Windows development. Linux/Mac people can still use it, but they will have a few errors to clean up.''</br>
# Open Visual Studio
# Once loaded, go to File -> New -> From Cookiecutter...
# Search for ''rimworld''
# Double-click ''cookiecutter-rimworld-mod-development''
# Change the Template Options:
## ''Create To'' => ''Your/Rimworld/Mod/Directory''
## ''mod_name''
## ''namespace_name'' (don't change if unsure)
## ''author'' => ''your steam username''
## ''target_version'' => current RW version (can leave blank for most up-to-date)
## ''in_game_description'' (not required, can change later in About-Release.xml)
## ''url'' (can leave blank for link to your Steam Workshop profile)
# Click "Create and Open Folder"

===Sharpdevelop===
'''Caution:''' Sharpdevelop (or #develop) does NOT CURRENTLY allow for C# 6.0+ syntax without plugins and does NOT ALLOW for C# 7.0+ syntax at all. For your average project this does not matter, however some existing projects are already built entirely upon C# 6.0+ syntax which can not be compiled anymore in Sharpdevelop. Visual Studio does not have these issues and should be your go-to for compiling large projects such as Combat Extended.

# Create a new class library project in your [[Modding Tutorials/Recommended software#IDE.27s|IDE of choice]];
## Go to File -> New -> Solution;
## Go to C# or .NET -> Library or Class Library (NOT portable);
## Enter a project name (solution name automatically updated);
## Choose a location, preferably:<br/><pre>(RimWorldInstallFolder)/Mods/(YourModName)/Source</pre>
## ''Optional'': Untick "Create a directory for solution"/"Create a project within the solution directory",
# In your project, add references to Assembly-CSharp.dll and UnityEngine.dll:
## In your IDE project file browser, right-click the "References" folder and "Add reference";
## Choose the ".NET Assembly Browser" tab and "Browse...";
## Navigate towards <pre>RimWorld******/RimWorld******_Data/Managed</pre> and select files: <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre>
## Click "Open" then "OK";
## In the References folder, right-click Assembly-CSharp -> Properties and change "Local copy" to False. Do the same for UnityEngine,
# In your project properties, change the target framework to .NET 4.7.2:
## In your IDE project file browser, right-click "(YourSolutionName)";
## Choose Properties;
## Go to the "Compiling" tab, "Output", "Target framework", "Change" and choose ".NET Framework 4.7.2",
# In your project properties, change the build events so only a single file is built:
## Go to the "Compiling" tab, "Output", "Debug info" and choose "No debug information";
## Right-click your .cs files -> Properties and change "Copy to output" (If you haven't resized the properties bar, this will be truncated to "Copy to out") to Never,
# In your project properties, fix the output location to put the DLL in the Assemblies folder:
## Go to the "Compiling" tab, "Output", "Output path" and change the output path to "..\..\Assemblies\".<br/><br/>

===Linux===

On Linux it is possible to develop using .NET packages provided by Microsoft:
# [https://dotnet.microsoft.com/download Install .NET by following the provided instructions.]
# If you use IDE, use it to build (no further details, not tested).
# It is possible to build from CLI using a .csproj file. Find a mod that has description pointing to its GitHub sources and copy from there ([https://github.com/llunak/rimworld-dietfiltersinstorage/blob/master/Source/DietFiltersInStorage.csproj example here]), or use another way to create a .csproj file.
# For building use a command like the following (substitute the proper .csproj file, change Release to Debug for a debug build):<br/><pre>dotnet build <project file>.csproj /property:Configuration=Release</pre>
# If you get errors, possibly the .csproj is Windows-specific and needs to be edited:
## You may need to fix paths (point them to .dll files in RimWorld/RimWorld*_Data/Managed, but it is generally better to use NuGet as described above in Option 2, as that is platform-independent).
## See other setups above for other settings (those IDEs write those settings to the .csproj files).

Note that .NET Framework from Microsoft is Windows-only, and some .csproj files do not build without it. Generally it seems those using Windows-specific paths are affected, while those platform-independent work fine. Either use Mono (see below), or use one that works. The example .csproj file linked above can usually be used as a drop-in replacement, with only properties in the first PropertyGroup needing adjustment. If you really want or need it, you can get .NET Framework from Mono, by additionally doing these steps:
# Install Mono (refer to your distribution's instructions);
# Change the build command to the following (4.7.2 is the .NET version from the .csproj file):<br/><pre>FrameworkPathOverride=$(dirname $(which mono))/../lib/mono/4.7.2-api/ dotnet build <project file>.csproj /property:Configuration=Release</pre>

===Xamarin/MonoDevelop===
The setup is similar as the one above. A few special points to address:
# Mono 4.X isn't backward compatible so you may need to install an older 3.X version of Mono in order to compile against .NET4.7.2 dlls.
# Make sure you uncheck "Use MSBuild build engine (recommended for this project type)" under project > options > build > general (You might find this by right-clicking on your project - not solution - name and selecting options)
# Changing the framework to 4.7.2 can be found (for Linux anyway) in the same place.

More detailed installation instructions for Linux can be found [https://blog.rubenwardy.com/2016/07/21/rimworld-setup-monodevelop/ here] and [https://spdskatr.github.io/RWModdingResources/mono-arch here]. Note that as of now (2021) these may be outdated, so if it doesn't work, you can try the steps described in the Mono section.

===Rider (good for Mac)===
JetBrains Rider is a great cross-platform C# IDE. Previously a paid product (with exceptions), it now offers a community license, making it free for non-commercial use.

# Open Rider and click New Solution in the welcome dialog.
## Click Class Library under .NET on the left. The option may take a second to show up.
## Under Solution Name (and Project Name), enter the name of your mod.
## Set the Solution Directory to [your mod folder]/Source.
## Optionally check "put solution and project in the same directory." This is probably a good idea.
## Change Framework to .Net Framework 4.7.2.
### If you're on Windows and 4.7.2 does not show up as an option, you will have to install the "4.7.2 Dev Pack" from [https://dotnet.microsoft.com/en-us/download/visual-studio-sdks Microsoft].
### If you're on MacOS, you may see an error "mono is not found"; install mono from [https://www.mono-project.com/docs/getting-started/install/mac/ here]. Additionally, if you do not have the option to choose .NET 4.7.2, you can create a project with the available NET option(s) and then manually edit the .csproj file to contain "<TargetFramework>net472</TargetFramework>" later.
## Click Create.
# In the left side bar, expand your solution, right click your project (mod name with "C#" icon) and click Properties.
## In the Properties window, select Configurations > Debug on the left and uncheck Debug Symbols.
## For both configurations, change the Output Path to ../../Assemblies.
## Click OK.
# Expand your project, right click References and click Add Reference.
## Click Add From.
## Browse to the folder with the RimWorld DLLs
### DLL Location for Mac: "/Users/[username]/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Contents/Resources/Data/Managed
### For Win10: "\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed"
## Select both Assembly-CSharp.dll and UnityEngine.dll and click OK.
## Expand Assemblies under References. For both of the assemblies that you just added:
### Right click the assembly and click Properties.
### Uncheck "Copy Local" (you may need to scroll down) and click OK.

You're done! Note that Rider has a built-in decompiler—to view the source of a RimWorld class or method, just right-click its name and click Go To > Definition.

===.NET Framework via Commmandline===
If you are on Windows and for some reason you don't want to use Visual Studio, you can also use the C# compiler that comes with the .NET Framework from within the terminal.

# Install the [https://dotnet.microsoft.com .NET Framework].
# (Optional) Adding the compiler to PATH.
## Search for "env" -> Edit system environment variables -> click on "Environment Variables" -> Edit the Path of the user variables -> Add the folder of csc.exe (Usually C:\Windows\Microsoft.NET\Framework\vX.X.XXXXX).
# Find <br/><pre>Assembly-CSharp.dll
UnityEngine.CoreModule.dll</pre> in your game files(Usualy at: C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\).
# Open a terminal and cd to the location of your .cs file.
# Compile your .cs file (If you skipped adding csc.exe to path, replace it with its full filepath in the following command).
## It should look something like this:<pre>csc.exe /t:library /r:"C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\Assembly-CSharp.dll","C:\Program Files (x86)\Steam\steamapps\common\RimWorld\RimWorldWin64_Data\Managed\UnityEngine.CoreModule.dll" MyMod.cs</pre>
## The command is structured where:<pre>csc.exe</pre> is the compiler(or the whole filepath), and:<pre>/r:"...","..."</pre> is the filepath of both gamefiles from step 3, and:<pre>MyMod.cs</pre> is your C# source code.
# Explanation:
## the /t flag sets it to be a .dll file.
## the /r flag references the game files(Not the decompiled source code, the game files).

===Visual Studio Code via Dev Container===
{{Recode|section=1|reason=Section commented out due to unknown, unvalidated source. Ideally a full guide for VCS needs to be written}}


=Common issues=
* Can't find the option to target .NET Framework 4.7.2? It may require additional installation steps. In Visual Studio, Tools => Get Tools and features => Individual Components => Select ''.NET Framework 4.7.2 development tools'' (or google installation instructions). Also make sure your project is a ''Class Library (.NET '''Framework''')''. Not .NET Core or .NET Standard.

=See also=
* [[Modding Tutorials/Writing custom code|Writing custom code]] continues on setting up your solution.<br/>

[[Category:Modding tutorials]]

Modding Tutorials/GameComponent

2025-11-21T20:07:51Z

Aelanna:

{{BackToTutorials}}
<small>< [[Modding Tutorials/Custom Comp Classes]]</small><br/>

{{:Modding_Tutorials/Outdated}}

Although neither explicitly nor formally linked, Map-, World- and GameComponents share a very similar design (and because of that they also share one tutorial). Similar to [[Modding Tutorials/ThingComp|ThingComp]], you can add any custom code to your Map-, World- or GameComponents for you to call manually. It also has methods called at specific occurrences that you can override.

'''Benefits''':<br/>
<nowiki>+</nowiki> Are very well supported by RimWorld.<br/>
<nowiki>+</nowiki> Generally safe to add to existing saves.</br>
<nowiki>+</nowiki> Work at a very global level.<br/>
<nowiki>+</nowiki> Can save data.<br/>
<nowiki>+</nowiki> Certain functionality gets automatically called by RimWorld.<br/>
<nowiki>+</nowiki> Can be employed to achieve lots of different types of functionality.<br/>
<nowiki>+</nowiki> Are always accessible.<br/>

'''Downsides''':<br>
<nowiki>-</nowiki> Removing a mod with these types of components from a save-game results in a (mostly harmless) one-time error.<br/>
<nowiki>-</nowiki> Does not expose any of its functionality to XML.<br/><br/>

== Requirements ==
* You need to have [[Modding Tutorials/Setting up a solution|set up your editor and environment]]
* You need to know [[Modding Tutorials/Writing custom code|how to write custom code]]
* A [[Modding Tutorials/Decompiling_source_code|decompiler]] helps, because this tutorial isn't going to tell you the exact implementation details of the Map-, World- or GameComponents.

== What you'll learn ==
How to use Map-, World- or GameComponents, for the price of one.

== Setting up ==
RimWorld will automatically create an instance of all classes that inherit from Map-, World- or GameComponent.

To implement a Map-, World-, or GameComponent, we need to inherit from the respective class and implement a parametered constructor inheriting from base. See [[Modding Tutorials/GameComponent#Example Code|example]]. This constructor tells your Map-, World-, or GameComponent what Map, World, or Game it belongs to.

Note that you'll need ''using RimWorld.Planet;'' for WorldComponents.

== Example Code ==
<source lang ="csharp">
using RimWorld;
using Verse;
using RimWorld.Planet;

namespace MyExampleMod
{
public class MyExampleWorldComponent : WorldComponent
{
public bool myExampleBool = true;

public MyExampleWorldComponent(World world) : base(world)
{
}
}
}
</source>
And there we have it. That creates an instance of a WorldComponent. We can then put things like a tracker for "How often did we trade with Faction X" in, or [[Modding Tutorials/GameComponent#Overridable methods of Map-, World- or GameComponent|override one or more of the accessible methods.]] Since these types of components are accessible from pretty much anywhere, they lend themselves to a wide variety of uses.

== Accessing your Map-, World- or GameComponent ==
These all follow the same design that [[Modding Tutorials/ThingComp|ThingComp]] follows; GetComponent<''TYPE''>().
===MapComponent===
First off: Know that null is a perfectly valid value for a Map:
* Players can abandon all their maps and just caravan around.
* A pawn on a Caravan is in a null map.
* A pawn inside a ThingHolder (Carried by another pawn, inside a cryptosleep casket or transport pod, inside a Corpse) is in a null map.
Trying to access your Component from something that is null leads to bad things happening. Null-check.

====From a Thing on a map====
<source lang ="csharp">
thing.Map.GetComponent<MyExampleMapComponent>();
</source>
Note: If the thing in question is inside a ThingHolder, use thing.MapHeld instead. That iterates through the ThingHolders until it finds a Map (or null) to return.

====From the currently visible map====
<source lang ="csharp">
Find.CurrentMap.GetComponent<MyExampleMapComponent>();
</source>
Note: Ensure that you want your MapComponent to do stuff on the ''currently visible'' map. thing.Map is often better.

====From who knows where====
If you want to play it safe, you can add something like the below to your MapComponent class to return it like so:
<source lang ="csharp">
public static MyExampleMapComponent GetMapComponentFor(Map map)
{
if (map == null)
{
Log.Error("Called GetMapComponent on a null map");
return null;
}

if (map.GetComponent<MyExampleMapComponent>() == null)
{
map.components.Add(new MyExampleMapComponent(map));
}
return map.GetComponent<MyExampleMapComponent>();
}
</source>
The safety this design offers is two-fold: It null checks the Map and gives a useful warning, and it handles the rare case where something went wrong with instantiating the MapComponent. This can happen when your MapComponent caused an exception during instantiation, or when a MapComponent that was loaded before yours threw an exception during itsinstantiation.

===WorldComponent===
<source lang ="csharp">
Find.World.GetComponent<MyExampleWorldComponent>();
</source>

===GameComponent===
<source lang ="csharp">
Current.Game.GetComponent<MyExampleGameComponent>();
</source>
'''Gotcha:''' The constructor should take a parameter of type ''Game'' (or you'll get errors saying "Constructor not found")

Note the difference in Current vs Find for Game vs Map- and World Components.

== Overridable methods of Map-, World- or GameComponent ==
'''NOTE''': This is up to date for version 1.0.2150. For the most up-to-date info, grab a decompiler.</br>
'''NOTE''': Not every method listed here is available to all three types of Component.</br>
'''NOTE''': Mentally replace TYPE with the type associated with your Component, be it Map, World or Game.</br>

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

===TYPEComponentUpdate===
Runs per frame, even when the game is paused. Best used for things that need updating regardless of [[Time|tickrate]], but it's unwise to put game logic here.

===TYPEComponentTick===
Runs per Tick.

===TYPEComponentOnGUI===
Runs per frame, when the TYPE is currently visible. Not available to WorldComponent. Useful for adding GUI stuff.

===ExposeData===
{{Main|Modding Tutorials/ExposeData}}
Saves data.

===FinalizeInit===
Called when RimWorld is done instantiating the TYPE. This runs after your constructor.

FinalizeInit runs after creating a new instance of TYPE and when loading. If you need instance data from your TYPE (like a WeatherManager, LordManager whatever else) this is the place. This is also the place to initialise your TYPEComponent if your constructor is at risk of throwing: There is no try/catch logic in instantiating new components, but there is for FinalizeInit. Throwing an exception in your constructor '''will''' cause issues with generating the Game/World/Map, whereas throwing in FinalizeInit ''may'' cause issues.

===StartedNewGame===
Unique to GameComponent. Almost, but not quite, entirely unlike FinalizeInit.

===LoadedGame===
Unique to GameComponent. Left as an exercise to the reader.

===MapGenerated===
Unique to MapComponent. Left as an exercise to the reader.

===MapRemoved===
Unique to MapComponent. Left as an exercise to the reader.

[[Category: Modding tutorials]]
[[Category: Modding]]

Modding Tutorials/Modifying classes

2025-11-11T07:05:01Z

Aelanna: Clarifying the difference between extension methods and actual class methods.

{{BackToTutorials}}

=Changing methods=
Use [[Modding Tutorials/Harmony| Harmony]].

=Adding fields to classes=
You can't. Not even with [[Modding Tutorials/Harmony| Harmony]]. Maybe you want to [[Modding_Tutorials/Def_classes| subclass]] instead?

=Adding methods to classes=
Yes and no. You can create [https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/extension-methods extension methods] that are syntactic sugar for calling static methods, but extension methods do not have access to protected or private fields or methods that an actual class method would.

For example, if you wanted to add a method to Pawn which would tell you if that pawn has a specific trait, you could do the following:

<source lang="csharp">
using RimWorld;
using Verse;

namespace MyExampleClassExtension
{
public static class PawnExtensions
{
public static bool HasTrait(this Pawn pawn, TraitDef trait)
{
return pawn.story.traits.HasTrait(trait);
}
}
}
</source>

This can then be called like so:

<source lang="csharp">
bool isNudist = pawn.HasTrait(TraitDefOf.Nudist)
</source>

Note the first argument to HasTrait: `this Pawn Pawn` -- that tells C# that you are defining an extension method on the Pawn class.

=Adding fields to Defs=
You can. The game support something called a [[Modding Tutorials/DefModExtension| DefModExtension]]. If you have a Def, you can get your mod extension from it. This allows you to add any custom field to any def.

=Adding behaviour to the Thing class=
If it's a ThingWithComps, you can add a [[Modding Tutorials/ThingComp|ThingComp]] instead. Almost all Things are a ThingWithComps. ThingComps can also be used to store whatever data you need.

=Adding behaviour to the Hediff class=
HediffWithComps also support comps. HediffComps are different from [[Modding Tutorials/ThingComp|ThingComp]]s, but their general use is the same.

=Using Harmony to override a non-overridden method=
You can't. Harmony can only patch methods which are actually implemented. You can't patch what isn't there.

Alternatives:
* [[Modding_Tutorials/Modifying_classes#Patching_the_base_class_of_a_subclass|Patch the base]] class instead, then check for the instance.
* [[Modding_Tutorials/Modifying_classes#Adding_fields_or_methods_to_classes|Subclass]], and then replace it wherever it's created with Harmony.

=Patching the base class of a subclass=
[[Modding Tutorials/Harmony|Harmony]] can only patch methods that actually have IL code. What you can do is patch the parent class. Let your patch take the __instance of the parent and pattern match.
<source lang="csharp">
if (!(__instance is SubClass))
return;
</source>

[[Category:Modding tutorials]][[Category:Modding]]

Modding Tutorials/Textures

2025-10-29T16:40:03Z

Aelanna: Added note about texture overwriting

{{DISPLAYTITLE:Mod Textures}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

(Work in progress) This is a guide for creating and adding textures to RimWorld mods.

== Creating Mod Textures ==

As a Unity game, RimWorld is capable of loading textures using a variety of formats. Most textures used in mods are transparent PNG files, but RimWorld is also capable of loading JPG, PSD, and even [https://en.wikipedia.org/wiki/DirectDraw_Surface DDS files].

# While RimWorld's vanilla textures are drawn in a vector style, vector art is not required and many of the original Core textures were actually raster assets. Using whichever technique you are more comfortable with!
# RimWorld texture resolutions are independent of their draw size in-game, and are generally sized relative to their draw size on screen. Most original vanilla textures use a resolution of 64 pixels per tile, but newer DLC textures and most mod artists use a resolution of 128 ppt as a baseline. Some mod artists will use texture resolutions of 256 ppt or higher, but this is generally considered excessive, not to mention highly detailed textures can clash with RimWorld's art style. Textures that are too large will also take up a lot more VRAM and RimWorld will simply crash if the GPU's VRAM is filled.
# The final dimension of a RimWorld texture should be a multiple of four and ideally a power of two (32x32, 64x64, 128x128, 256x256, etc). This makes it easier for GPUs to load and work with.
# RimWorld's art style dictates that interactive objects such as items and buildings should have a thick black outline, generally equal to 2px of thickness per 64px of tile resolution. Plants generally have a green instead of black outline.
# It is strongly recommended that you reference vanilla textures when creating mod textures. Ludeon publishes an [https://www.dropbox.com/sh/mz6zjq3f1d654f3/AACX_OMdBG_J78hF2Ph-HzM3a?e=1&dl=0|Official RimWorld Art Source] that contains almost all vanilla and DLC textures for modders to reference for this purpose.
# Textures should be placed in the Textures folder of the [[Modding_Tutorials/Mod_Folder_Structure|mod folder structure]]. Note that all textures from all mods are loaded into the same content loader, thus it is strongly recommended that you either prefix your texture names or place them in a uniquely named folder to minimize the chance of colliding with another mod.
# Texture file resolution begins in the Textures folder. Thus, if you have a texture that is placed in <code>Textures/MyMod/MyTexture.png</code>, then the path you need to use to reference it would simply be <code>MyMod/MyTexture</code>.
# All textures from the vanilla game and all mods are loaded into the same space in the Unity content finder, thus reusing the same path as a vanilla texture or another mod will cause the last one loaded to overwrite the other(s). This can be done intentionally for a re-texture mod, but otherwise it's strongly recommended that you prefix either your folders or files with a unique name to reduce the chance of unintended collision. (i.e. <code>MyMod/Things/MyTexture</code> or <code>Things/MyMod_MyTexture</code>)

== Texture Masking ==

Stuffable or paintable objects can use a texture mask to determine which parts of the texture should be colored or not. For a typical texture mask, black is used to prevent coloring and 100% red is used to specify that the primary color should be drawn. A darker shader of red will result in less of the color being multiplied in; for example, <code>#BB0000</code> would result in the stuff or paint color being applied at 75% strength.

The following example from the [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon tutorial]] makes it so that only the blade of the machete is painted with the stuff color, leaving the handle the default texture color.

<div class="TwoColumnCollapsibleLayout">
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Weapon Texture</div>
<div class="TwoColumnCollapsibleLayout-text">
[[File:ExampleWeapon Machete.png|none]]
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Texture Mask</div>
<div class="TwoColumnCollapsibleLayout-text">
[[File:ExampleWeapon Machete_m.png|none]]
</div>
</div>
</div>

Very rarely, a second color channel is used for certain textures, such as the assignment color on beds (colonist, medical, prisoner, etc). Areas of the texture that should be painted with the secondary color should use green instead of red. Red and green can be mixed if blending is desired, as the strength of the color applied is based on the value of the red or green color channel.

== Use-specific Recommendations ==

The following are texture recommendations for specific use cases.

=== Weapons ===

Melee weapons should be drawn with the point of the weapon facing to the right, as when pawns are facing west it will be mirrored horizontally. <code><equippedAngleOffset></code> in the weapon's <code><graphicData></code> is used to angle the weapon into a more natural orientation, with the vast majority of vanilla melee weapons being -65 degrees, -25 degrees ([[Ikwa|ikwa]]), or -20 degrees ([[Thrumbo horn|thrumbo horns]], [[Elephant tusk|elephant tusks]]).

[[File:MeleeExampleGrid.png|none|border]]

Ranged weapons should also be drawn aiming to the right, with the additional consideration that the barrel or point of origin for projectiles should be vertically centered in the texture to ensure that it lines up with where projectiles are actually spawned.

[[File:RifleExampleGrid.png|none|border]]

For weapons with lopsided extensions such as a suppressed pistol, it is generally recommended to keep the body of the weapon centered and to expand the canvas so that the weapon looks correct when wielded. You can increase the <code><drawSize></code> of a weapon in its <code><graphicData></code> to compensate if necessary.

[[File:PistolExampleGrid.png|none|border]]

Projectiles should be drawn facing upwards, with the center of the texture at the exact coordinate position of the projectile in-game. Note that unlike weapons, projectile textures are ''not'' flipped when facing west.

[[File:ProjectileExampleGrid.png|none|border]]

=== Apparel ===

By default, headwear and body apparel textures are overlaid 1:1 onto heads and bodies respectively, thus it is strongly recommended that you start with a vanilla body or apparel texture as a template. (Please see links above for the official art source.)

Headwear requires a minimum of 3 textures, one each for south, north, and east facings. A west facing is optional; RimWorld will mirror your east texture if none is provided, so you only need to provide one for asymmetric apparel or if you want the west texture to be different from the east texture. An additional texture can be used to represent the apparel on the ground, thus a total of 3+1 textures is recommended for headwear, 6+2 if you use texture masks.

Body apparel has the same texture usage, but for each of the 5 vanilla body types (male, female, thin, hulk, and fat) for a total of 15+1 textures or 30+2 with texture masks.

Utility packs such as tox gas canisters can be set to render using a single texture but with offsets based on body type. This only works for utility-slot items and has the same texture requirements as headwear (3+1, or 6+2 with masks).

=== Plants ===
''See [[Modding_Tutorials/Plant_Rendering|Plant Rendering]].''

=== Pawns ===
''See [[Modding_Tutorials/Pawn_Rendering|Pawn Rendering]].'' (Placeholder)

=== Buildings ===

For buildings, it is generally recommended to use a canvas sized precisely for the <code><drawSize></code> of the building. Centering the texture against the canvas also ensures that you do not have to mess with draw offsets to make it align properly.

The following is a sample texture for a <code><size>(2,2)</size></code> table with <code><drawSize>(3,3)</drawSize></code> which results in a canvas size of 384x384 at 128 pixels per tile.

[[File:BuildingExampleGrid.png|none|border]]

=== Walls and Conduits ===

Walls and conduits use a special graphic type called a "linked atlas". This is a spritesheet of 16 separate subtextures representing all possible tile link configurations printed onto a single master texture.

The red overlaid areas are culled from the texture and will not be shown. The green arrows indicate link directions.

[[File:WallExampleGrid.png|none|border]]

=== Terrain ===

Terrain in RimWorld uses a single texture painted over a 16x16 tile area. This texture should be tileable in all directions to ensure smooth display over large areas.

[[File:TerrainExampleGrid.png|none|border]]

== Tips and Tricks ==

* Unless you are using a Unity asset bundle to disable compression, textures loaded into RimWorld will be compressed in memory. This can result in a white outline around your textures due to the fact that some art programs will discard all color data in fully transparent pixels. This can be fixed by either instructing your art program to preserve color data (preferably black) in transparent pixels, or by adding an extra 1% opacity black outline around the regular outline of the object texture.

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Assets

2025-10-27T15:59:54Z

Aelanna: Marking guide as outdated until it can be rewritten or replaced.

{{BackToTutorials}}<br/>

{{:Modding_Tutorials/Outdated}}

In this tutorial you will learn how to extract the base assets of RimWorld.

=Requirements=
# [https://github.com/SeriousCache/UABE Unity Assets Bundle Extractor] to extract the contents of the unity .asset archives.
# or [https://github.com/Perfare/AssetStudio AssetStudio]

=UnityEx=
To extract the original files from the Unity asset archives we will be using UnityEx which is compatible with Rimworld 1.0's Archives.<br/>

#Download UnityEx either by searching using your search engine of choice or [https://yadi.sk/d/m3vFWoQ3j62Cr via this link].
#Place the UnityEX.exe somewhere easily locatable (I prefer to place it into the Rimworld Directory).
#Run UnityEX.exe and open the .asset file you would like to extract, for example; <pre>RimWorld\RimWorldWin64_Data\resources.assets</pre>
#Extract the files you need. If you are extracting .tex files you can use "Extract with convert", this will convert the .tex files to .dds.
#The extracted files will be placed into a new folder in the same directory (Unity_Assets_Files) as the .asset file you have extracted.

=Unity Assets Bundle Extractor=
To extract the original files from the Unity asset archives we will be using Unity Assets Bundle Extractor which is compatible with Rimworld 1.0's Archives.<br/>

#Download Unity Assets Bundle Extractor by searching using your search engine of choice or [https://github.com/SeriousCache/UABE via this link].
#Unzip it.
#Run AssetBundleExtractor.exe and open the .asset file you would like to extract, for example, <pre>RimWord\RimWorldWin64_Data\resources.assets</pre>
#Select the files you need/want. Then, click "Plugins" and select "Export to .png" or "Export sound". Note that this only works when you select files by type: so select only audio files or only textures.
#Click OK and select a folder for storage.

=AssetStudio=
To extract the original files from the Unity asset archives we will be using AssetStudio which is compatible with Rimworld 1.5's Archives (older versions not tested).<br/>

#Download AssetStudio by searching using your search engine of choice or [https://github.com/Perfare/AssetStudio via this link], if you are unsure which .NET runtime version you have installed net472 should be fine.
#Unzip it.
#Run AssetStudioGUI.exe and open the asset file you would like to extract, for example with '''File -> Load file''', <pre>RimWord\RimWorldWin64_Data\resources.assets</pre> or for the DLC Asset Bundles with '''File -> Load folder''' <pre>RimWorld\Data\Anomaly\AssetBundles</pre>
#Switch to the Asset List tab.
#Select the files you need/want. Then, right click and select "Export selected assets", works for audio and textures.
#Select a folder for storage and click open.

=AssetStudio on Linux=

#Download AssetStudio by searching using your search engine of choice or [https://github.com/Perfare/AssetStudio via this link]. Use the .net 6 version (AssetStudio.net6.v0.16.47.zip)
#Install [https://github.com/bottlesdevs/Bottles Bottles] however is appropriate for your distro. [https://aur.archlinux.org/packages/bottles Here] is the AUR link for arch users
#Unzip AssetStudio.net6.v0.16.47.zip (e.g /home/username/applications/AssetStudio.net6.v0.16.47/)
#Open Bottles and and click the + symbol in the top left corner of the UI to 'Create New Bottle'
#In the 'Create New Bottle' options window that pops up enter a name (e.g 'AssetStudio') and select 'Application'. You can leave the other options as default.
#Once the AssetStudio bottle has been created and has automatically opened the details page click on 'Add Shortcuts...'
#Navigate to where you extracted AssetStudio and select 'AssetStudioGUI.exe'
#After you have selected the exe you'll be on the bottle Detail page again, this time select 'Dependencies' and from the list choose 'dotnetcoredesktop6'
#After the .net dependency is installed you can now click the play button next to 'AssetStudioGUI' and the application will launch
#Open the asset file you would like to extract, for example with '''File -> Load file''', <pre>RimWord\RimWorldWin64_Data\resources.assets</pre> or for the DLC Asset Bundles with '''File -> Load folder''' <pre>RimWorld\Data\Anomaly\AssetBundles</pre>
#Switch to the Asset List tab.
#Select the files you need/want. Then, right click and select "Export selected assets", works for audio and textures.
#Select a folder for storage and click open.

Notes: You could wait unzip AssetStudio in the Bottles prefix folder if you want to want to keep it all together (e.g /home/username/.local/share/bottles/bottles/AssetStudio/drive_c/Program Files/AssetStudio.net6.v0.16.47/). This would require waiting for step 5 to be complete (creating the bottle) prior to unzipping so that the folder structure exists.

AssetStudio.net6.v0.16.47 is used in this tutorial as it uses the most recent version of .net however the dependency for .net472 can be installed in Bottles (dotnet472) so AssetStudio.net472.v0.16.47.zip could presumably be used if there was a need.

<gallery>
Bottles create 1.png|'Create New Bottle' dialog box in Bottles
Bottles create 2.png|'Details' page for a newly created bottle in Bottles
Bottles create 3.png|Bottles 'Dependencies' screen with correct dependency highlighted
Bottles create 4.png|Completed bottle with AssetStudioGUI ready to run and use
</gallery>

=See also=
* [[Modding Tutorials/Recommended software#Graphics Software|Recommended graphics software]] for suggestions on software for further editing or viewing of source files.<br/>

[[Category:Modding tutorials]]

Time

2025-10-27T15:38:05Z

Aelanna: Removed the confusing "1.44 Min" because nothing in RimWorld actually measures time in-game by minutes, it always goes straight from hours to seconds.

<noinclude>
{| align=center
| {{Gameplay_Nav}}
|}
----

</noinclude>
'''Time''' in RimWorld is split into two related systems - [[#Real time|real time]], that is the time experienced by the player, and [[#In-game time|in-game time]], that is time that passes in the gameworld of the colony and experienced by the pawns themselves.

== Real time ==
Time in RimWorld passes as a series of ticks. On normal game speed, there are 60 such ticks to a real second; there are always 2,500 ticks to one in-game hour.

{| {{STDT|c_01 text-right}}
! colspan='2' | In-Game Time
! colspan='1' | Ticks
! colspan='1' | Real Time
|-
! 1 Sec
| || | 60 || 1s
|-
! 1 Hour
| 60 Min || | 2,500 || | ~42s
|-
! 1 Day
|| 24 Hours || 60,000 || | 16m 40s
|-
! 1 Quadrum
|| 15 Days || 900,000 || 4h 10m
|-
! 1 Year
|| 4 Quadrums || 3,600,000 || 16h 40m
|}
{| {{STDT|c_01 text-right}}
|-
! colspan='3' | Technical details for modders
|-
!
! Ticks
! Time
|-
| 1 tick || 1 tick || 1/60th second
|-
| 1 rare tick || 250 ticks || 4.16 seconds
|-
| 1 long tick || 2000 ticks || 33.33 seconds
|}

The player also has access to play speed controls that attempt to multiply the rate at which game time progresses. Note that depending on a number of technical factors including the machine on which the game is being run, it may not be possible to run the game at the target speed. In this case, the game will run as close to the target as possible and, as such, the limit will be more noticeable at higher speeds.

The speeds are described in the table below. The speeds controls can be selected by the buttons on the lower right hand sode of the screen, or by key binds. Note that Speeds 2, 3, and 4 are sometimes described by the community as 2x, 3x, and 4x speed, however this is not representative of the actual speed.

{| class="wikitable"
|-
! Speed !! Default key binding !! Game speed multiplier !! Button
|-
| Pause || {{Key|Space}} || x0 || [[File:TimeSpeedButton Pause.png]]
|-
| 1 || {{Key|1}} || x1 || [[File:TimeSpeedButton Normal.png]]
|-
| 2 || {{Key|2}} || x3 || [[File:TimeSpeedButton Fast.png]]
|-
| 3 || {{Key|3}} || x6 || [[File:TimeSpeedButton Superfast.png]]
|-
| 4 || {{Key|4}} || x15 || N/A
|}
Note that Speed 4 is only available when [[development mode]] is active and is only available by key bind.

== In-game time ==
{{Stub|section=1|reason=Exploration of [[Temperature]]/Season link and [[Light]]/Season link}}
{{Quote|The year is divided into 4 quadrums* of 15 days each. Quadrums are the same everywhere, while seasons are different in different places}}
Time on the rimworld proceeds largely as one would expect except for three primary differences. Years only last 60 days, years are separated into 4 15-day "quadrums" instead of months, and the year is seasonal - that is, last season ends at the same time as the year. Note that times given in-game will use this system - thus if something ''"spoils in 1 year"'', you have 60 in-game days, not 365.

Like terrestrial seasons, the [[temperature]] changes with progression of the quadrums and the temperature effects depend on the latitude. When it is "Summer" in the Northern Hemisphere, it is "Winter" in the Southern, and vice versa, while areas near the equator remain temperate year-round.

Each quadrums is given a name that is a portmanteau of the terrestrial months of the ''season'' that quadrum is equivalent to, rather than named for months in the same period of the year. Thus, Aprimay is a portmanteau of April and May, but is the start of the year and relates to Spring in the North, but Fall in the South. Mouse-hovering over the in-game date in the lower right-hand corner will list what "local seasons" each quadrum represents for the settlement currently viewed.

The names of these 4 quadrums are:

{| class="wikitable"
|-
! Name !! Northern Season !! Southern Season !! Days
|-
! Aprimay
| Spring || Fall || 1 to 15
|-
! Jugust
| Summer || Winter || 16 to 30
|-
! Septober
| Fall || Spring || 31 to 45
|-
! Decembary
| Winter || Summer || 46 to 60
|}

The game starts in the year 5500, and by default begins in Spring (Aprimay or Septober). In colder biomes, the season will adjust to Summer, to allow players to survive and grow plants, although some colder biomes there is permanent winter, and this changes nothing. Starting season may be changed in [[World generation#Advanced settings|World Generation]].

===Time of day===
Days in RimWorld last 24 hours, or {{Ticks|60,000}}. The in-game clock is in 24-hour format, with the hours displayed in military time from 0h to 23h. The time of day has a few effects on gameplay:
*Time determines the level of [[light]] outdoors.
*Plants can only grow from 6:00 to 19:12.
*[[Night owl]]s consider it "Day time" from 11h to 18h, and "Night time" from 23h to 6h.

[[Light|Daylight]] length is also tied to the season and latitude - the day will be independent of the season at the equator but get longer in the Summer and shorter in the Winter the further north or south you go. Exact details of the relationship between season, latitude and day length are currently unknown.

The hour of the day is relative to the location on the [[Menus#World|World map]]. If it's noon (1200) at your home base, it will still be late morning (1100/11 AM) a bit to the west, and already early afternoon (1300/1 PM) a bit to the east, as "time zones" are in our world. Time of day is modeled on the planet view; local time of day corresponds to how the sunlight hits the planet.

===Work===
Items in game list values with names like "Work to build", "Work to uninstall", or "[[Work To Make]]" in their info boxes. One unit of work is approximately {{Ticks|60}}. Note that the work values are rounded to display nicely as seconds, and the actual tick amounts are used by the game engine, not the displayed work.

== Version history ==
* [[Version/0.0.254B|0.0.254B]] - Abolished cycles - dates are measured in days only.
* [[Version/0.10.785|0.10.785]] - Day length extended from 24,000 to 30,000 ticks. Days per month reduced from 12 to 10.
* [[Version/0.13.1135|0.13.1135]] - Days are now twice as long as before, with years being half as many days i.e. years are exactly as long as before in actual play time, just divided into a smaller number of longer days. The year is now split into seasons instead of months.
* [[Version/0.17.1546|0.17.1546]] - As season names could no longer be consistently applied to the entire globe, necessitating that they be named as month-like "quadrums."

[[Category:Game mechanics]]

Modding Tutorials

2025-10-09T02:51:14Z

Aelanna: /* Updates and Migrations */

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
{{Stub|section=1|reason= Where does [[Modding Tutorials/Rituals]] fit in the below categories?}}
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)

===Updates and Migrations ===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]] - (WARNING: Odyssey Spoilers) Community notes for updating mods from 1.5 to 1.6.

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun_(1.1)|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Testing mods|Testing Mods]]
** [[Modding Tutorials/Testing mods#Development mode|Development Mode]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Research Projects

2025-10-07T19:38:52Z

Aelanna: /* Fields */

{{DISPLAYTITLE:Research Projects}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

Research projects are used to gate access to buildings and crafting recipes behind the use of the [[Research]] system.

''Last updated: 2025-10-06 (RimWorld v1.6)''

== <code>ResearchProjectDef</code> ==

Research projects are defined in XML using <code>ResearchProjectDef</code> [[Modding_Tutorials/Defs|Defs]]. As with all Defs, looking at the vanilla examples is a great way to get a feel for how the system is used.

=== Fields ===

The following are valid fields in <code>ResearchProjectDef</code>. All of these fields are optional unless otherwise specified.

<div class="TutorialTableWrapper">
{| class="TutorialCodeTable"
! XML Example !! Description
|-
| <source lang="xml">
<baseCost>1000</baseCost>
</source>
| class="TutorialCodeTable-description" |
The base cost to complete this research project. The final cost of this project will be modified by tech level differences between the player's faction and that of the research project. A research project must either have a <code>baseCost</code> or a <code>knowledgeCost</code> (see below).
|-
| <source lang="xml">
<preqrequisites>
<li>Electricity</li>
<li>Batteries</li>
</preqrequisites>
</source>
| class="TutorialCodeTable-description" |
All of a project's prerequisites must be completed before research on it can begin. Prerequisites on the same tab will be linked to the project with a line.
|-
| <source lang="xml">
<hiddenPreqrequisites>
<li>Machining</li>
</hiddenPreqrequisites>
</source>
| class="TutorialCodeTable-description" |
Hidden prerequisites work exactly the same as regular prerequisites except that lines will not be drawn between this project and its hidden prerequisites. Using them can be useful in reducing visual clutter.
|-
| <source lang="xml">
<techLevel>Industrial</techLevel>
</source>
| class="TutorialCodeTable-description" |
The tech level of this research project. Valid options are: '''Undefined''', '''Animal''', '''Neolithic''', '''Medieval''', '''Industrial''', '''Spacer''', '''Ultra''', and '''Archotech'''. As tech levels are defined via an enum rather than via Defs, it is effectively impossible to define new ones without major compatibility problems.
|-
| <source lang="xml">
<requiredByThis></requiredByThis>
</source>
| class="TutorialCodeTable-description" |
This field is present on <code>ResearchProjectDef</code> but is not used anywhere in vanilla XML, nor does the field appear to be utilized by any C# code. Its purpose is unknown.
|-
| <source lang="xml">
<researchMods></researchMods>
</source>
| class="TutorialCodeTable-description" |
A code hook for wiring up C# classes that will be notified when this research project is completed. This was used in early alpha versions of RimWorld for research projects such as Gun Turret Cooling which permanently increased the burst shot count of improvised turrets from 3 to 4, but is no longer used.
|-
| <source lang="xml">
<requiredResearchBuilding>HiTechResearchBench</requiredResearchBuilding>
</source>
| class="TutorialCodeTable-description" |
If specified, this research project can only be researched at this particular research bench. Note that there is no concept of progression with research benches; if you specify the simple research bench as a required research building then it will not be researchable at a hi-tech research bench.
|-
| <source lang="xml">
<requiredResearchFacilities>
<li>MultiAnalyzer</li>
</requiredResearchFacilities>
</source>
| class="TutorialCodeTable-description" |
Specifies one or more research bench attached facilities that are required to work on this research project. Due to the aforementioned lack of research bench progression and the amount of space that research benches take up in a colony, it is generally recommended to gate modded research projects behind facilities rather than custom research benches if a gatekeeper building is desired. Attached facilities can also be made non-buildable and only obtainable from traders or quests to make them more difficult to acquire.
|-
| <source lang="xml">
<tags>
<li>ClassicStart</li>
<li>TribalStart</li>
</tags>
</source>
| class="TutorialCodeTable-description" |
Tags are used to specify this research project as a starting project for starting scenarios.
|-
| <source lang="xml">
<tab>MyCustomResearchTab</tab>
</source>
| class="TutorialCodeTable-description" |
If specified, will use the designated tab instead of the vanilla research tab. See Custom Research Tabs below for more details.
|-
| <source lang="xml">
<researchViewX>1</researchViewX>
<researchViewX>1.4</researchViewY>
</source>
| class="TutorialCodeTable-description" |
Specifies the position within its tab that this research project appears at within the vanilla research window. See Research Tab Layout below for more details.
|-
| <source lang="xml">
<discoveredLetterTitle>About: My Custom Tech</discoveredLetterTitle>
<discoveredLetterText>You have discovered a unique technology that unlocks phenomenal cosmic powers!</discoveredLetterText>
</source>
| class="TutorialCodeTable-description" |
If used, generates a letter when this research project is completed. The following vanilla research projects use this: Electricity, Fabrication, Starflight Basics, and Standard Gravtech.
|-
| <source lang="xml">
<discoveredLetterDisabledWhen>
<bigThreatsDisabled>true</bigThreatsDisabled>
</discoveredLetterDisabledWhen>
</source>
| class="TutorialCodeTable-description" |
Used to disable the discovered letter when certain game mechanics are disabled due to difficulty settings. Valid options here are: <code>bigThreatsDisabled</code>, <code>trapsDisabled</code>, <code>turretsDisabled</code>, <code>mortarsDisabled</code>, <code>extremeWeatherIncidentsDisabled</code>. This is only used in vanilla for Starflight Basics, which disables the letter warning the player about the raids during reactor startup if big threats (raids) are disabled.
|-
| <source lang="xml">
<techprintCount>2</techprintCount>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Specifies the number of techprints required to unlock this research project. Note that if the Royalty DLC is not loaded, then this project will be freely researchable so long as its other requirements are met.
|-
| <source lang="xml">
<techprintCommonality>1</techprintCommonality>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Specifies the commonality of this project's techprints if applicable. Defaults to 1.0.
|-
| <source lang="xml">
<techprintMarketValue>1000</techprintMarketValue>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Overrides the [[Market Value]] of this research project's techprints if applicable. Defaults to 1000.
|-
| <source lang="xml">
<heldByFactionCategoryTags>
<li>Empire</li>
</heldByFactionCategoryTags>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) If specified, then techprints for this research project are only available from factions with the specified tag. Faction category tags are arbitrary strings, with the following used by vanilla factions: Tribal, Outlander, Ancient, Empire {{RoyaltyIcon}}, OutlanderRefugee {{RoyaltyIcon}}, Beggars {{IdeologyIcon}}, Pilgrims {{IdeologyIcon}}, Sanguophages {{BiotechIcon}}, HoraxCult {{AnomalyIcon}}, Salvager {{OdysseyIcon}}, and TradersGuild {{OdysseyIcon}}.
|-
| <source lang="xml">
<hideWhen>
<turretsDisabled>true</turretsDisabled>
</hideWhen>
</source>
| class="TutorialCodeTable-description" |
Hides this research project if certain game mechanics are disabled by difficulty settings. Valid options here are: <code>bigThreatsDisabled</code>, <code>trapsDisabled</code>, <code>turretsDisabled</code>, <code>mortarsDisabled</code>, <code>extremeWeatherIncidentsDisabled</code>.
|-
| <source lang="xml">
<requiresMechanitor>true</requiresMechanitor>
</source>
| class="TutorialCodeTable-description" |
([[Biotech]] {{BiotechIcon}} Only) If set to true, then this research project can only be researched by a [[mechanitor]].
|-
| <source lang="xml">
<requiredAnalyzed>
<li>SignalChip</li>
</requiredAnalyzed>
</source>
| class="TutorialCodeTable-description" |
If specified, then the linked CompAnalyzable items must be analyzed before progress on this research project can be started.
|-
| <source lang="xml">
<recalculatePower>true</recalculatePower>
</source>
| class="TutorialCodeTable-description" |
If specified, forces existing power networks to recalculate their network load upon completion of this research project. Only used in vanilla by Colored Lights, which halves the power cost of vanilla electrical lamps.
|-
| <source lang="xml">
<knowledgeCategory>Basic</knowledgeCategory>
</source>
| class="TutorialCodeTable-description" |
([[Anomaly]] {{AnomalyIcon}} Only) If specified, determines the <code>KnowledgeCategoryDef</code> that this research project belongs in. Vanilla Anomaly has Basic and Advanced.
|-
| <source lang="xml">
<knowledgeCost>30</knowledgeCost>
</source>
| class="TutorialCodeTable-description" |
([[Anomaly]] {{AnomalyIcon}} Only) The knowledge cost to complete this research project. A research project cannot have both a <code>baseCost</code> and a <code>knowledgeCost</code>.
|-
| <source lang="xml">
<teachConcept>Fishing</teachConcept>
</source>
| class="TutorialCodeTable-description" |
If specified, triggers the designated <code>ConceptDef</code> in the Learning Helper upon completion of this research project. The only vanilla research projects that use this are Fishing and Void Provocation.
|-
| <source lang="xml">
<generalRules>
<rulesStrings>
<li>subject->multi-analysis</li>

<li>subject_story->automated a research laboratory</li>
<li>subject_story->unlocked the trans-spectrum secrets of the universe</li>
<li>subject_story->helped identify new stable isotopes</li>

<li>subject_gerund->constructing multi-analyzers</li>
</rulesStrings>
</generalRules>
</source>
| class="TutorialCodeTable-description" |
If provided, is used to generate descriptive flavor text for [[Schematic|schematics]]. Research projects without generalRules will never have schematics generated for them.
|-
| <source lang="xml">
<requireGravEngineInspected>true</requireGravEngineInspected>
</source>
| class="TutorialCodeTable-description" |
([[Odyssey]] {{OdysseyIcon}} Only) If set to true, then this research project can only be started after a working grav engine has been inspected. Only used by Standard Gravtech in vanilla.
|-
| <source lang="xml">
<customUnlockTexts>
<li>Fishing zones</li>
</customUnlockTexts>
</source>
| class="TutorialCodeTable-description" |
Adds arbitrary text lines to the "unlocks" segment of this research project's description in the research window. Only used by [[Fishing]] in vanilla.
|-
|}
</div>

=== Research Tab Layout ===

Research projects are laid out in the vanilla research UI using a simple coordinate system defined by <code><researchViewX></code> and <code><researchViewY></code>. note that while the X-axis increments by 1, the Y-axis increments by 0.7.

[[File:ResearchView.png|none|border]]

Note that research projects that occupy the same grid location (usually from multiple mods trying to use the same location) will cause the projects to get staggered in the research window. It is generally recommended to use a custom research tab if you have sufficient research projects to justify it.

== Custom Research Tabs ==

Custom research tabs can be used by creating a <code>ResearchTabDef</code>, then specifying this in the <code><tab></code> field of your <code>ResearchProjectDef</code>.

<source lang="xml">
<ResearchTabDef>
<defName>MyCustomResearchTab</defName>
<label>My Mod</label>
<generalTitle>Custom mod research</generalTitle>
<generalDescription>Fancy-pants research unlocked by my super-cool mod.</generalDescription>
</ResearchTabDef>
</source>

== Using Custom Research ==

The following vanilla Def types support one or more research projects as a prerequisite:

<div class="TutorialTableWrapper">
{| class="TutorialCodeTable"
! XML Object !! Field
|-
| RecipeDef || researchPrerequisite (single)
|-
| RecipeDef || researchPrerequisites (list)
|-
| BuildableDef (includes ThingDef) || researchPrerequisites (list only)
|-
| PlantProperties || sowResearchPrerequisites (list only)
|-
| RecipeMakerProperties || researchPrerequisite (single)
|-
| RecipeMakerProperties || researchPrerequisites (list)
|-
| TerrainTemplateDef || researchPrerequisites (list only)
|-
| DesignationCategoryDef || researchPrerequisites (list only)
|-
| PsychicRitualDef || researchPrerequisites (list only)
|-
|}
</div>

== Checking Research Completion ==

Checking whether a research project has been completed from C# can be done by obtaining the <code>ResearchProjectDef</code> and calling the <code>IsFinished</code> property. If you need to do this often, then it's recommended you use a [[Modding_Tutorials/Linking_XML_and_C|DefOf]] to obtain a static reference to it.

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Overhaul workspace

2025-10-07T03:45:44Z

Aelanna: /* Modding Basics */

{{DISPLAYTITLE:Overhaul Workspace}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

'''NOTE''': This is a workspace for the ongoing overhaul of the RimWorld Wiki's modding tutorials and references. If you managed to find your way here, please check out the main [[Modding_Tutorials|modding tutorials index page]] instead.

This overhaul is being overseen by the '''#mod-development''' channel on the [https://discord.gg/rimworld RimWorld Discord], please contact us before changing anything.

== Modding Basics ==

<div class="TwoColumnCollapsibleLayout">
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Modding Basics</div>
<div class="TwoColumnCollapsibleLayout-text">
* Getting Started
* [[Modding_Tutorials/Recommended software|Recommended Software]]
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]]
* [[Modding_Tutorials/About.xml|About.xml]]
* [[Modding_Tutorials/Textures|Textures]]
* [[Modding_Tutorials/Sounds|Sounds]]
* [[Modding_Tutorials/Localization|Localization]]
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">XML</div>
<div class="TwoColumnCollapsibleLayout-text">
* Defs
* ThingDef
* [[Modding Tutorials/MayRequire|MayRequire]]
* [[Modding Tutorials/PatchOperations|PatchOperations]]
* [[Modding Tutorials/Research Projects|Research Projects]]
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">C#</div>
<div class="TwoColumnCollapsibleLayout-text">
* C# Basics
* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - Reading compiled code from the base game as well as DLCs and other mods.
* [[Modding_Tutorials/Setting up a solution|Setting up]] - (Needs cleanup)
* Harmony Primer
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Code References</div>
<div class="TwoColumnCollapsibleLayout-text">
* [[Modding_Tutorials/Infrastructure_Overview|Infrastructure Overview]]
* [[Modding_Tutorials/Application_Startup|Application Startup]]
* [[Modding_Tutorials/Simulation_Lifecycle|Simulation Lifecycle]]
* [[Modding_Tutorials/Rendering_Lifecycle|Rendering Lifecycle]]
* [[Modding_Tutorials/Buildings|Buildings]]
* [[Modding_Tutorials/Pawns|Pawns]]
* [[Modding_Tutorials/Audio|Audio]]
</div>
</div>
</div>

== Tutorials ==
This will be a curated subset of tutorials that will be vetted, reviewed, and maintained by the overhaul team. These are meant to be a cohesive set of tutorials that guides the reader from the simplest single-Def items such as weapons to building a full custom faction.

=== Basic Tutorials (XML) ===
* [[Modding_Tutorials/Basic_Melee_Weapon|Creating a custom melee weapon]]
* [[Modding_Tutorials/Basic_Ranged_Weapon|Creating a custom ranged weapon]]
* [[Modding_Tutorials/Basic_Plant|Creating a custom plant]]
* [[Modding_Tutorials/Basic_Animal|Creating a custom animal]]
* [[Modding_Tutorials/Basic_Building|Creating a simple building]]
* [[Modding_Tutorials/Basic_Workbench|Creating a custom workbench]]
* [[Modding_Tutorials/Basic_Drug|Creating a custom drug]]

=== Advanced Tutorials (XML) ===
* [[Modding_Tutorials/Advanced_Faction|Creating a custom faction]]
* [[Modding_Tutorials/Advanced_Culture|Creating a custom culture]]
* [[Modding_Tutorials/Advanced_Trader|Creating a custom trader type]]

=== Basic Tutorials (C#) ===
* [[Modding_Tutorials/Basic_Consumable|Creating a custom consumable]]

=== Advanced Tutorials (C#) ===
* [[Modding_Tutorials/Advanced_Texture_Overlays|Creating custom texture overlays]]

[[Category:Modding tutorials]]

== Banner Templates ==

{{:Modding_Tutorials/Under_Review}}
<nowiki>{{:Modding_Tutorials/Under_Review}}</nowiki>

{{:Modding_Tutorials/Marked_for_Deletion}}
<nowiki>{{:Modding_Tutorials/Marked_for_Deletion}}</nowiki>

{{:Modding_Tutorials/Obsolete}}
<nowiki>{{:Modding_Tutorials/Obsolete}}</nowiki>

{{:Modding_Tutorials/Outdated}}
<nowiki>{{:Modding_Tutorials/Outdated}}</nowiki>

Modding Tutorials/Overhaul workspace

2025-10-07T03:44:05Z

Aelanna:

{{DISPLAYTITLE:Overhaul Workspace}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

'''NOTE''': This is a workspace for the ongoing overhaul of the RimWorld Wiki's modding tutorials and references. If you managed to find your way here, please check out the main [[Modding_Tutorials|modding tutorials index page]] instead.

This overhaul is being overseen by the '''#mod-development''' channel on the [https://discord.gg/rimworld RimWorld Discord], please contact us before changing anything.

== Modding Basics ==

<div class="TwoColumnCollapsibleLayout">
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Modding Basics</div>
<div class="TwoColumnCollapsibleLayout-text">
* Getting Started
* [[Modding_Tutorials/Recommended software|Recommended Software]]
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]]
* [[Modding_Tutorials/About.xml|About.xml]]
* [[Modding_Tutorials/Textures|Textures]]
* [[Modding_Tutorials/Sounds|Sounds]]
* [[Modding_Tutorials/Research_Projects|Research Projects]]
* [[Modding_Tutorials/Localization|Localization]]
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">XML</div>
<div class="TwoColumnCollapsibleLayout-text">
* Defs
* ThingDef
* [[Modding Tutorials/MayRequire|MayRequire]]
* [[Modding Tutorials/PatchOperations|PatchOperations]]
* [[Modding Tutorials/Research Projects|Research Projects]]
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">C#</div>
<div class="TwoColumnCollapsibleLayout-text">
* C# Basics
* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - Reading compiled code from the base game as well as DLCs and other mods.
* [[Modding_Tutorials/Setting up a solution|Setting up]] - (Needs cleanup)
* Harmony Primer
</div>
</div>
<div class="TwoColumnCollapsibleLayout-section">
<div class="TwoColumnCollapsibleLayout-subtitle">Code References</div>
<div class="TwoColumnCollapsibleLayout-text">
* [[Modding_Tutorials/Infrastructure_Overview|Infrastructure Overview]]
* [[Modding_Tutorials/Application_Startup|Application Startup]]
* [[Modding_Tutorials/Simulation_Lifecycle|Simulation Lifecycle]]
* [[Modding_Tutorials/Rendering_Lifecycle|Rendering Lifecycle]]
* [[Modding_Tutorials/Buildings|Buildings]]
* [[Modding_Tutorials/Pawns|Pawns]]
* [[Modding_Tutorials/Audio|Audio]]
</div>
</div>
</div>

== Tutorials ==
This will be a curated subset of tutorials that will be vetted, reviewed, and maintained by the overhaul team. These are meant to be a cohesive set of tutorials that guides the reader from the simplest single-Def items such as weapons to building a full custom faction.

=== Basic Tutorials (XML) ===
* [[Modding_Tutorials/Basic_Melee_Weapon|Creating a custom melee weapon]]
* [[Modding_Tutorials/Basic_Ranged_Weapon|Creating a custom ranged weapon]]
* [[Modding_Tutorials/Basic_Plant|Creating a custom plant]]
* [[Modding_Tutorials/Basic_Animal|Creating a custom animal]]
* [[Modding_Tutorials/Basic_Building|Creating a simple building]]
* [[Modding_Tutorials/Basic_Workbench|Creating a custom workbench]]
* [[Modding_Tutorials/Basic_Drug|Creating a custom drug]]

=== Advanced Tutorials (XML) ===
* [[Modding_Tutorials/Advanced_Faction|Creating a custom faction]]
* [[Modding_Tutorials/Advanced_Culture|Creating a custom culture]]
* [[Modding_Tutorials/Advanced_Trader|Creating a custom trader type]]

=== Basic Tutorials (C#) ===
* [[Modding_Tutorials/Basic_Consumable|Creating a custom consumable]]

=== Advanced Tutorials (C#) ===
* [[Modding_Tutorials/Advanced_Texture_Overlays|Creating custom texture overlays]]

[[Category:Modding tutorials]]

== Banner Templates ==

{{:Modding_Tutorials/Under_Review}}
<nowiki>{{:Modding_Tutorials/Under_Review}}</nowiki>

{{:Modding_Tutorials/Marked_for_Deletion}}
<nowiki>{{:Modding_Tutorials/Marked_for_Deletion}}</nowiki>

{{:Modding_Tutorials/Obsolete}}
<nowiki>{{:Modding_Tutorials/Obsolete}}</nowiki>

{{:Modding_Tutorials/Outdated}}
<nowiki>{{:Modding_Tutorials/Outdated}}</nowiki>

Modding Tutorials

2025-10-07T03:41:52Z

Aelanna: Added link to research project guide

{| align=center
| {{Mods_Nav}}
|}
<hr>

This is the hub page for tutorials, guides, and reference materials for creating mods for RimWorld. If you are looking for instructions on how to use RimWorld, please check out the general [[Modding]] hub.

As RimWorld does not have a formal modding API, nearly all of the information here has been gathered and maintained by the modding community.

'''NEW: [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.'''

-----

==About RimWorld==
{{Stub|section=1|reason= Where does [[Modding Tutorials/Rituals]] fit in the below categories?}}
RimWorld is a multi-platform game written on Unity 2022.3.35. However, the Unity Editor is not used for creating mods unless you are creating new shaders or building optional asset bundles.

* [[Modding_Tutorials/Recommended_software|Recommended Software]] - Editors and other useful software for mod development
* [[Modding_Tutorials/Mod_Folder_Structure|Mod Folder Structure]] - Explore the basic folder structure of a mod
** [[Modding_Tutorials/About.xml|About.xml]] - About.xml identifies and describes your mod to RimWorld so that it can be loaded properly

===Game Systems Guides===

* [[Modding_Tutorials/Defs|Defs]] - XML Definitions are used to define and configure content in a way that does not require compiling code
** [[Modding_Tutorials/MayRequire|MayRequire]] - MayRequire and MayRequireAnyOf are used to conditionally load Defs and list entries based on whether a DLC or other mod is loaded
* [[Modding_Tutorials/Localization|Localization]] - Define text strings used for translations and word lists used in name and text generation
* [[Modding_Tutorials/PatchOperations|PatchOperations]] - PatchOperations are used to modify XML Defs without overwriting them completely
* [[Modding_Tutorials/Sounds|Sounds]] - (Needs Rewriting) Adding sound files for mods
* [[Modding_Tutorials/Textures|Textures]] - How to create and add textures to mods
* [[Modding Tutorials/Plant Rendering|Plant Rendering]] - An explanation of how plant textures are rendered
* [[Modding_Tutorials/Research_Projects|Research Projects]] - How to create and use research projects.

===XML Tutorials===

The following are step-by-step tutorials for creating basic content mods.

Basic Tutorials:
* [[Modding_Tutorials/Basic_Melee_Weapon|Basic Melee Weapon]] - How to create a basic melee weapon with a texture mask
* [[Modding_Tutorials/Basic_Ranged_Weapon|Basic Ranged Weapon]] - How to create a basic ranged weapon with custom sound effects
* [[Modding_Tutorials/Basic_Plant|Basic Plant]] - How to create a custom plant with both a cultivated and wild variant
* Custom Animal (Upcoming)
* Simple Building (Upcoming)
* Custom Workbench (Upcoming)
* Custom Drug (Upcoming)

Advanced Tutorials:
* Custom Faction (Upcoming)
* Custom Culture (Upcoming)
* Custom Trader Type (Upcoming)

===C# Guides===

C# is used to create and define custom game behaviors

* [[Modding_Tutorials/Decompiling source code|Decompiling Source Code]] - How to set up and use a decompiler to read vanilla game code
* [[Modding_Tutorials/Setting up a solution|Setting up a Solution]] - How to set up a solution for compiling a custom mod assembly
* [[Modding_Tutorials/Application_Startup|Application Startup]] - Describes the application startup process and the order in which game data is loaded
* Custom Consumable (Upcoming)
* Custom Overlays (Upcoming)

===Updates and Migrations ===

* [[Modding_Tutorials/RimWorld_1.5_Mod_Updates|RimWorld 1.5 Mod Updates]] - (WARNING: Anomaly Spoilers) Community notes for updating mods from 1.4 to 1.5.
* [[Modding_Tutorials/RimWorld_1.6_Mod_Updates|RimWorld 1.6 Mod Updates]]''' - A work-in-progress list of changes datamined by the modding community in the current unstable version of RimWorld 1.6. '''THERE MAY BE ODYSSEY DLC SPOILERS, YOU HAVE BEEN WARNED.

===Slightly Outdated===

* [[Modding_Tutorials/Plague_Gun_(1.1)|Plague Gun]] - This tutorial was created for RimWorld 1.0 but updated for 1.4. While the exact content is obsolete as you can now accomplish the same result with purely vanilla XML, it is still useful as a crash course for end-to-end mod creation and is here until newer tutorials can replace it.

===Uploading to Steam Workshop===
* You can upload your mod to Steam Workshop by enabling Development Mode from your game Options and then using the Upload option under the Advanced button in the vanilla mod manager.
* Note that in order to upload to Steam Workshop, you must own the game on Steam Workshop. Owning RimWorld on GOG or Epic will not work.
* Your Preview.png should be a 640x360 or 1280x720 PNG and '''must''' be under 1MB. If it is too large, then your upload will be rejected with <code>Error : Limit Exceeded</code>
* If you get a <code>OnItemSubmitted Fail</code> error, make sure you close any programs that are targeting items in your mods folder. This can also mean that Steam Workshop is having some technical issues at the moment. If it keeps occurring, then the only thing to do is to wait a few hours for it to clear up.
* Steam mod descriptions don't use markdown, they use a variant of BBCode. Please check out the [https://steamcommunity.com/comment/Guide/formattinghelp Steam text formatting guide].

-----

'''Note:''' All of the above tutorials have been cleaned up and reviewed by the #mod-development team on the [https://discord.gg/rimworld RimWorld Discord] in cooperation with RimWorld Wiki staff editors. Please let us know before creating, adding, or making any major edits to the vetted tutorials and guides section!

==Outdated / Under Review==

The following tutorials are either out of date or in need of a rewrite. The information in them might be useful but may not be up to standard; please be aware of any potential inaccuracies until they can be addressed.

* [[Modding Tutorials/First Steps|First Steps and Some Links]]
* [[Modding Tutorials/Essence| Essence of Modding]]
* [[Modding Troubleshooting Tips and Guides]]
* [[Modding Tutorials/Testing mods|Testing Mods]]
** [[Modding Tutorials/Testing mods#Development mode|Development Mode]]
* [[Modding Tutorials/Sounds|Adding and Testing Sounds]]
* [[Modding Tutorials/Assets|Decompiling Texture/Sound Assets]]
* [[Modding Tutorials/Compatibility|Compatibility]]
* [[Modding_Tutorials/Distribution|Distribution]]
* [[Modding_Tutorials/Modifying defs|Modifying Defs]]
* [[Modding_Tutorials/Troubleshooting|Troubleshooting mods]]

===XML tutorials===

* [[Modding Tutorials/XML file structure|XML File Structure]]
* [[Modding Tutorials/XML Defs|Introduction to XML Defs]]
** [[Modding Tutorials/Compatibility with defs|XML Def Compatibility]]
** [[Modding Tutorials/ThingDef|ThingDef explained]]
** [[Modding Tutorials/Weapons Guns|Weapons_Guns.xml explained]]. Slightly dated.

===C# tutorials===
* [[Modding_Tutorials/Hello World|Hello World]]
* [[Modding_Tutorials/Writing custom code|Writing Custom Code]]
* [[Modding Tutorials/Linking XML and C#|Linking XML and C#]]
* [[Modding_Tutorials/Harmony|Alter Code at Runtime with Harmony]] - this is a best practice for modifying game code, replacing C# code injection to reduce Mod Conflicts
* [[Modding_Tutorials/Modifying classes|Adding fields and methods to classes]]
* [[Modding Tutorials/ModSettings|Mod settings]] - Add settings to your mod
* [[Modding Tutorials/DefModExtension|Def mod extensions]] - Add (custom) fields to Defs
* [[Modding Tutorials/Custom Comp Classes|Custom Comp Classes]] - A quick overview of what types of Comps there are, and what they're suited for.
* [[Modding_Tutorials/ThingComp|ThingComp]] - Learn all there is to know about ThingComps.
* [[Modding Tutorials/GameComponent|Components]] - GameComponents, WorldComponents, and MapComponents
* [[Modding_Tutorials/Def classes|Introduction to Def Classes]]
* [[Modding_Tutorials/Compatibility_with_DLLs|Using Harmony to optionally patch other mods for the sake of compatibility]]
* [[Modding Tutorials/TweakValue|TweakValues]] - Change values on the fly (handy for quick iteration!)
* [[Modding Tutorials/ExposeData|ExposeData]] - Save stuff
* [[Modding Tutorials/BigAssListOfUsefulClasses|The big ass list of useful classes]] - A non-exhaustive list of classes you'll use most
* [[Modding Tutorials/GrammarResolver|Grammar Resolver]] - PAWN_objective, PAWN_possessive? Find out what it all means here.
* [https://github.com/Mehni/ExampleJob/wiki ExampleJob] - Mehni's top to bottom breakdown of Jobs.
* [[Modding_Tutorials/ConfigErrors|Config Errors]] - Provide configuration issues to the user on startup.
* [[Modding Tutorials/DebugActions|Debug Actions]] - Call methods from the debug menu
* [https://www.arp242.net/rimworld-mod-linux.html Getting started with RimWorld modding on Linux]

===Art Tutorials===
* [https://spdskatr.github.io/RWModdingResources/artstyle Artstyle] - Officially unofficial guide to RimWorld's Artstyle
* [https://www.reddit.com/r/RimWorld/comments/5tn1pi/rimworldstyle_sprite_tutorials/ Ekksu's guide to creating RimWorld animals]
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1114369188 ChickenPlucker's guide to creating apparel]
* [https://github.com/seraphile/rimshare/wiki/Colouring-in-Images Seraphile's guide to masks]

===Under Construction===

These are currently unfinished and need to be cleaned up or removed

* [[Modding Tutorials/Quests]]
* [[Modding Tutorials/Troubleshooting/Finding Exceptions]]

===Dangerously Outdated===

* [[RimWorld 1.3: XML Mod Creation]]
* [[Modding Tutorials/Assembly Modding Example|Assembly Modding]]
* [[Plague Gun (1.1)|The Plague Gun]] tutorial originally by Jecrell, updated to 1.1+.
* [[Modding Tutorials/Xenotype template]] originally by Ryflamer

* [[Modding Tutorials/Smelter]]
* [[Modding Tutorials/Items]]
* [[Modding Tutorials/Furniture]]

==External Links==
* [https://github.com/roxxploxx/RimWorldModGuide/wiki Roxxploxx's set of modding tutorials]
* [https://spdskatr.github.io/RWModdingResources/ RimWorld Modding Resources - A hub for guides, modders, practical tips]

[[Category:Modding]]
[[Category:Modding tutorials]]

Modding Tutorials/Research Projects

2025-10-07T03:40:57Z

Aelanna: New research project modding guide.

{{DISPLAYTITLE:Research Projects}}

{{BackToTutorials}}

{{:Modding_Tutorials/Under_Review}}

Research projects are used to gate access to buildings and crafting recipes behind the use of the [[Research]] system.

''Last updated: 2025-10-06 (RimWorld v1.6)''

== <code>ResearchProjectDef</code> ==

Research projects are defined in XML using <code>ResearchProjectDef</code> [[Modding_Tutorials/Defs|Defs]]. As with all Defs, looking at the vanilla examples is a great way to get a feel for how the system is used.

=== Fields ===

The following are valid fields in <code>ResearchProjectDef</code>. All of these fields are optional unless otherwise specified.

<div class="TutorialTableWrapper">
{| class="TutorialCodeTable"
! XML Example !! Description
|-
| <source lang="xml">
<baseCost>1000</baseCost>
</source>
| class="TutorialCodeTable-description" |
The base cost to complete this research project. The final cost of this project will be modified by tech level differences between the player's faction and that of the research project. A research project must either have a <code>baseCost</code> or a <code>knowledgeCost</code> (see below).
|-
| <source lang="xml">
<preqrequisites>
<li>Electricity</li>
<li>Batteries</li>
</preqrequisites>
</source>
| class="TutorialCodeTable-description" |
All of a project's prerequisites must be completed before research on it can begin. Prerequisites on the same tab will be linked to the project with a line.
|-
| <source lang="xml">
<hiddenPreqrequisites>
<li>Machining</li>
</hiddenPreqrequisites>
</source>
| class="TutorialCodeTable-description" |
Hidden prerequisites work exactly the same as regular prerequisites except that lines will not be drawn between this project and its hidden prerequisites. Using them can be useful in reducing visual clutter.
|-
| <source lang="xml">
<techLevel>Industrial</techLevel>
</source>
| class="TutorialCodeTable-description" |
The tech level of this research project. Valid options are: '''Undefined''', '''Animal''', '''Neolithic''', '''Medieval''', '''Industrial''', '''Spacer''', '''Ultra''', and '''Archotech'''. As tech levels are defined via an enum rather than via Defs, it is effectively impossible to define new ones without major compatibility problems.
|-
| <source lang="xml">
<requiredByThis></requiredByThis>
</source>
| class="TutorialCodeTable-description" |
This field is present on <code>ResearchProjectDef</code> but is not used anywhere in vanilla XML, nor does the field appear to be utilized by any C# code. Its purpose is unknown.
|-
| <source lang="xml">
<researchMods></researchMods>
</source>
| class="TutorialCodeTable-description" |
A modder hook for wiring up C# classes that will be notified when this research project is completed. Not used in any vanilla research project. (More documentation needed, it is unknown if any mods actually use this.)
|-
| <source lang="xml">
<requiredResearchBuilding>HiTechResearchBench</requiredResearchBuilding>
</source>
| class="TutorialCodeTable-description" |
If specified, this research project can only be researched at this particular research bench. Note that there is no concept of progression with research benches; if you specify the simple research bench as a required research building then it will not be researchable at a hi-tech research bench.
|-
| <source lang="xml">
<requiredResearchFacilities>
<li>MultiAnalyzer</li>
</requiredResearchFacilities>
</source>
| class="TutorialCodeTable-description" |
Specifies one or more research bench attached facilities that are required to work on this research project. Due to the aforementioned lack of research bench progression and the amount of space that research benches take up in a colony, it is generally recommended to gate modded research projects behind facilities rather than custom research benches if a gatekeeper building is desired. Attached facilities can also be made non-buildable and only obtainable from traders or quests to make them more difficult to acquire.
|-
| <source lang="xml">
<tags>
<li>ClassicStart</li>
<li>TribalStart</li>
</tags>
</source>
| class="TutorialCodeTable-description" |
Tags are used to specify this research project as a starting project for starting scenarios.
|-
| <source lang="xml">
<tab>MyCustomResearchTab</tab>
</source>
| class="TutorialCodeTable-description" |
If specified, will use the designated tab instead of the vanilla research tab. See Custom Research Tabs below for more details.
|-
| <source lang="xml">
<researchViewX>1</researchViewX>
<researchViewX>1.4</researchViewY>
</source>
| class="TutorialCodeTable-description" |
Specifies the position within its tab that this research project appears at within the vanilla research window. See Research Tab Layout below for more details.
|-
| <source lang="xml">
<discoveredLetterTitle>About: My Custom Tech</discoveredLetterTitle>
<discoveredLetterText>You have discovered a unique technology that unlocks phenomenal cosmic powers!</discoveredLetterText>
</source>
| class="TutorialCodeTable-description" |
If used, generates a letter when this research project is completed. The following vanilla research projects use this: Electricity, Fabrication, Starflight Basics, and Standard Gravtech.
|-
| <source lang="xml">
<discoveredLetterDisabledWhen>
<bigThreatsDisabled>true</bigThreatsDisabled>
</discoveredLetterDisabledWhen>
</source>
| class="TutorialCodeTable-description" |
Used to disable the discovered letter when certain game mechanics are disabled due to difficulty settings. Valid options here are: <code>bigThreatsDisabled</code>, <code>trapsDisabled</code>, <code>turretsDisabled</code>, <code>mortarsDisabled</code>, <code>extremeWeatherIncidentsDisabled</code>. This is only used in vanilla for Starflight Basics, which disables the letter warning the player about the raids during reactor startup if big threats (raids) are disabled.
|-
| <source lang="xml">
<techprintCount>2</techprintCount>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Specifies the number of techprints required to unlock this research project. Note that if the Royalty DLC is not loaded, then this project will be freely researchable so long as its other requirements are met.
|-
| <source lang="xml">
<techprintCommonality>1</techprintCommonality>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Specifies the commonality of this project's techprints if applicable. Defaults to 1.0.
|-
| <source lang="xml">
<techprintMarketValue>1000</techprintMarketValue>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) Overrides the [[Market Value]] of this research project's techprints if applicable. Defaults to 1000.
|-
| <source lang="xml">
<heldByFactionCategoryTags>
<li>Empire</li>
</heldByFactionCategoryTags>
</source>
| class="TutorialCodeTable-description" |
([[Royalty]] {{RoyaltyIcon}} Only) If specified, then techprints for this research project are only available from factions with the specified tag. Faction category tags are arbitrary strings, with the following used by vanilla factions: Tribal, Outlander, Ancient, Empire {{RoyaltyIcon}}, OutlanderRefugee {{RoyaltyIcon}}, Beggars {{IdeologyIcon}}, Pilgrims {{IdeologyIcon}}, Sanguophages {{BiotechIcon}}, HoraxCult {{AnomalyIcon}}, Salvager {{OdysseyIcon}}, and TradersGuild {{OdysseyIcon}}.
|-
| <source lang="xml">
<hideWhen>
<turretsDisabled>true</turretsDisabled>
</hideWhen>
</source>
| class="TutorialCodeTable-description" |
Hides this research project if certain game mechanics are disabled by difficulty settings. Valid options here are: <code>bigThreatsDisabled</code>, <code>trapsDisabled</code>, <code>turretsDisabled</code>, <code>mortarsDisabled</code>, <code>extremeWeatherIncidentsDisabled</code>.
|-
| <source lang="xml">
<requiresMechanitor>true</requiresMechanitor>
</source>
| class="TutorialCodeTable-description" |
([[Biotech]] {{BiotechIcon}} Only) If set to true, then this research project can only be researched by a [[mechanitor]].
|-
| <source lang="xml">
<requiredAnalyzed>
<li>SignalChip</li>
</requiredAnalyzed>
</source>
| class="TutorialCodeTable-description" |
If specified, then the linked CompAnalyzable items must be analyzed before progress on this research project can be started.
|-
| <source lang="xml">
<recalculatePower>true</recalculatePower>
</source>
| class="TutorialCodeTable-description" |
If specified, forces existing power networks to recalculate their network load upon completion of this research project. Only used in vanilla by Colored Lights, which halves the power cost of vanilla electrical lamps.
|-
| <source lang="xml">
<knowledgeCategory>Basic</knowledgeCategory>
</source>
| class="TutorialCodeTable-description" |
([[Anomaly]] {{AnomalyIcon}} Only) If specified, determines the <code>KnowledgeCategoryDef</code> that this research project belongs in. Vanilla Anomaly has Basic and Advanced.
|-
| <source lang="xml">
<knowledgeCost>30</knowledgeCost>
</source>
| class="TutorialCodeTable-description" |
([[Anomaly]] {{AnomalyIcon}} Only) The knowledge cost to complete this research project. A research project cannot have both a <code>baseCost</code> and a <code>knowledgeCost</code>.
|-
| <source lang="xml">
<teachConcept>Fishing</teachConcept>
</source>
| class="TutorialCodeTable-description" |
If specified, triggers the designated <code>ConceptDef</code> in the Learning Helper upon completion of this research project. The only vanilla research projects that use this are Fishing and Void Provocation.
|-
| <source lang="xml">
<generalRules>
<rulesStrings>
<li>subject->multi-analysis</li>

<li>subject_story->automated a research laboratory</li>
<li>subject_story->unlocked the trans-spectrum secrets of the universe</li>
<li>subject_story->helped identify new stable isotopes</li>

<li>subject_gerund->constructing multi-analyzers</li>
</rulesStrings>
</generalRules>
</source>
| class="TutorialCodeTable-description" |
If provided, is used to generate descriptive flavor text for [[Schematic|schematics]]. Research projects without generalRules will never have schematics generated for them.
|-
| <source lang="xml">
<requireGravEngineInspected>true</requireGravEngineInspected>
</source>
| class="TutorialCodeTable-description" |
([[Odyssey]] {{OdysseyIcon}} Only) If set to true, then this research project can only be started after a working grav engine has been inspected. Only used by Standard Gravtech in vanilla.
|-
| <source lang="xml">
<customUnlockTexts>
<li>Fishing zones</li>
</customUnlockTexts>
</source>
| class="TutorialCodeTable-description" |
Adds arbitrary text lines to the "unlocks" segment of this research project's description in the research window. Only used by [[Fishing]] in vanilla.
|-
|}
</div>

=== Research Tab Layout ===

Research projects are laid out in the vanilla research UI using a simple coordinate system defined by <code><researchViewX></code> and <code><researchViewY></code>. note that while the X-axis increments by 1, the Y-axis increments by 0.7.

[[File:ResearchView.png|none|border]]

Note that research projects that occupy the same grid location (usually from multiple mods trying to use the same location) will cause the projects to get staggered in the research window. It is generally recommended to use a custom research tab if you have sufficient research projects to justify it.

== Custom Research Tabs ==

Custom research tabs can be used by creating a <code>ResearchTabDef</code>, then specifying this in the <code><tab></code> field of your <code>ResearchProjectDef</code>.

<source lang="xml">
<ResearchTabDef>
<defName>MyCustomResearchTab</defName>
<label>My Mod</label>
<generalTitle>Custom mod research</generalTitle>
<generalDescription>Fancy-pants research unlocked by my super-cool mod.</generalDescription>
</ResearchTabDef>
</source>

== Using Custom Research ==

The following vanilla Def types support one or more research projects as a prerequisite:

<div class="TutorialTableWrapper">
{| class="TutorialCodeTable"
! XML Object !! Field
|-
| RecipeDef || researchPrerequisite (single)
|-
| RecipeDef || researchPrerequisites (list)
|-
| BuildableDef (includes ThingDef) || researchPrerequisites (list only)
|-
| PlantProperties || sowResearchPrerequisites (list only)
|-
| RecipeMakerProperties || researchPrerequisite (single)
|-
| RecipeMakerProperties || researchPrerequisites (list)
|-
| TerrainTemplateDef || researchPrerequisites (list only)
|-
| DesignationCategoryDef || researchPrerequisites (list only)
|-
| PsychicRitualDef || researchPrerequisites (list only)
|-
|}
</div>

== Checking Research Completion ==

Checking whether a research project has been completed from C# can be done by obtaining the <code>ResearchProjectDef</code> and calling the <code>IsFinished</code> property. If you need to do this often, then it's recommended you use a [[Modding_Tutorials/Linking_XML_and_C|DefOf]] to obtain a static reference to it.

[[Category:Modding]]
[[Category:Modding tutorials]]