Research Projects

< Modding Tutorials

?

Under Review

This tutorial or guide is currently undergoing review and may be subject to further revision.

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)

ResearchProjectDef

Research projects are defined in XML using ResearchProjectDef 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 ResearchProjectDef. All of these fields are optional unless otherwise specified.

XML Example	Description
<baseCost>1000</baseCost>	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 baseCost or a knowledgeCost (see below).
<preqrequisites> <li>Electricity</li> <li>Batteries</li> </preqrequisites>	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.
<hiddenPreqrequisites> <li>Machining</li> </hiddenPreqrequisites>	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.
<techLevel>Industrial</techLevel>	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.
<requiredByThis></requiredByThis>	This field is present on ResearchProjectDef but is not used anywhere in vanilla XML, nor does the field appear to be utilized by any C# code. Its purpose is unknown.
<researchMods></researchMods>	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.
<requiredResearchBuilding>HiTechResearchBench</requiredResearchBuilding>	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.
<requiredResearchFacilities> <li>MultiAnalyzer</li> </requiredResearchFacilities>	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.
<tags> <li>ClassicStart</li> <li>TribalStart</li> </tags>	Tags are used to specify this research project as a starting project for starting scenarios.
<tab>MyCustomResearchTab</tab>	If specified, will use the designated tab instead of the vanilla research tab. See Custom Research Tabs below for more details.
<researchViewX>1</researchViewX> <researchViewX>1.4</researchViewY>	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.
<discoveredLetterTitle>About: My Custom Tech</discoveredLetterTitle> <discoveredLetterText>You have discovered a unique technology that unlocks phenomenal cosmic powers!</discoveredLetterText>	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.
<discoveredLetterDisabledWhen> <bigThreatsDisabled>true</bigThreatsDisabled> </discoveredLetterDisabledWhen>	Used to disable the discovered letter when certain game mechanics are disabled due to difficulty settings. Valid options here are: bigThreatsDisabled, trapsDisabled, turretsDisabled, mortarsDisabled, extremeWeatherIncidentsDisabled. 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.
<techprintCount>2</techprintCount>	(Royalty 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.
<techprintCommonality>1</techprintCommonality>	(Royalty Only) Specifies the commonality of this project's techprints if applicable. Defaults to 1.0.
<techprintMarketValue>1000</techprintMarketValue>	(Royalty Only) Overrides the Market Value of this research project's techprints if applicable. Defaults to 1000.
<heldByFactionCategoryTags> <li>Empire</li> </heldByFactionCategoryTags>	(Royalty 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 , OutlanderRefugee , Beggars , Pilgrims , Sanguophages , HoraxCult , Salvager , and TradersGuild .
<hideWhen> <turretsDisabled>true</turretsDisabled> </hideWhen>	Hides this research project if certain game mechanics are disabled by difficulty settings. Valid options here are: bigThreatsDisabled, trapsDisabled, turretsDisabled, mortarsDisabled, extremeWeatherIncidentsDisabled.
<requiresMechanitor>true</requiresMechanitor>	(Biotech Only) If set to true, then this research project can only be researched by a mechanitor.
<requiredAnalyzed> <li>SignalChip</li> </requiredAnalyzed>	If specified, then the linked CompAnalyzable items must be analyzed before progress on this research project can be started.
<recalculatePower>true</recalculatePower>	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.
<knowledgeCategory>Basic</knowledgeCategory>	(Anomaly Only) If specified, determines the KnowledgeCategoryDef that this research project belongs in. Vanilla Anomaly has Basic and Advanced.
<knowledgeCost>30</knowledgeCost>	(Anomaly Only) The knowledge cost to complete this research project. A research project cannot have both a baseCost and a knowledgeCost.
<teachConcept>Fishing</teachConcept>	If specified, triggers the designated ConceptDef in the Learning Helper upon completion of this research project. The only vanilla research projects that use this are Fishing and Void Provocation.
<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>	If provided, is used to generate descriptive flavor text for schematics. Research projects without generalRules will never have schematics generated for them.
<requireGravEngineInspected>true</requireGravEngineInspected>	(Odyssey 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.
<customUnlockTexts> <li>Fishing zones</li> </customUnlockTexts>	Adds arbitrary text lines to the "unlocks" segment of this research project's description in the research window. Only used by Fishing in vanilla.

Research Tab Layout

Research projects are laid out in the vanilla research UI using a simple coordinate system defined by <researchViewX> and <researchViewY>. note that while the X-axis increments by 1, the Y-axis increments by 0.7.

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 ResearchTabDef, then specifying this in the <tab> field of your ResearchProjectDef.

<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>

Using Custom Research

The following vanilla Def types support one or more research projects as a prerequisite:

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)

Checking Research Completion

Checking whether a research project has been completed from C# can be done by obtaining the ResearchProjectDef and calling the IsFinished property. If you need to do this often, then it's recommended you use a DefOf to obtain a static reference to it.