Difference between revisions of "Modding Tutorials/MayRequire"

Revision as of 21:19, 4 June 2023

?

Under Review

This tutorial or guide is currently undergoing review and should not be considered ready to use.

MayRequire is an XML attribute introduced alongside the Royalty DLC that allows for easy conditional loading of XML content. MayRequire makes it easier to load content that is optionally dependent on DLCs or other mods.

Details

MayRequire is inserted as an XML attribute in a supported XML node with a value being one or more packageId values separated by commas.

The packageId for official DLCs are:

Royalty: Ludeon.RimWorld.Royalty
Ideology: Ludeon.RimWorld.Ideology
Biotech: Ludeon.RimWorld.Biotech

The packageId for mods can be found in their About.xml file.

`MayRequireAnyOf`

By default, MayRequire will only allow the use of that node if all of the DLCs or mods it designates are loaded. If you instead want to load the specified node if any of the specified DLCs or mods are loaded, you can use MayRequireAnyOf instead.

List Entries

MayRequire can be on any li node to only load that entry if the specified DLC or mod is loaded:

XML Example	Description
<ThingDef ParentName="BasePawn"> <defName>Human</defName> <label>human</label> <!-- irrelevant nodes omitted --> <recipes> <li>ExciseCarcinoma</li> <li>AdministerMechSerumHealer</li> <li>RemoveBodyPart</li> <li>Euthanize</li> <li>Anesthetize</li> <li>CureScaria</li> <li MayRequire="Ludeon.RimWorld.Biotech">Vasectomy</li> <li MayRequire="Ludeon.RimWorld.Biotech">ReverseVasectomy</li> <li MayRequire="Ludeon.RimWorld.Biotech">TubalLigation</li> <li MayRequire="Ludeon.RimWorld.Biotech">ExtractOvum</li> <li MayRequire="Ludeon.RimWorld.Royalty">CureBloodRot</li> <li MayRequire="Ludeon.RimWorld.Royalty">CureAbasia</li> <li MayRequire="Ludeon.RimWorld.Biotech">ExtractHemogenPack</li> <li MayRequire="Ludeon.RimWorld.Biotech">BloodTransfusion</li> <li MayRequire="Ludeon.RimWorld.Biotech">ImplantXenogerm</li> <li MayRequire="Ludeon.RimWorld.Biotech">ImplantIUD</li> <li MayRequire="Ludeon.RimWorld.Biotech">RemoveIUD</li> <li MayRequire="Ludeon.RimWorld.Biotech">TerminatePregnancy</li> </recipes> <!-- irrelevant nodes omitted --> </ThingDef>	`MayRequire` is used in the Human ThingDef to set surgery recipes that are only relevant to specific DLCs. Without `MayRequire`, these would cause errors as the specified Defs only exist in their respective DLCs.
<SurgeryOutcomeEffectDef Name="SurgeryOutcomeBase"> <defName>SurgeryOutcomeBase</defName> <outcomes> <li Class="SurgeryOutcomeSuccess" /> <!-- irrelevant nodes omitted --> <li Class="SurgeryOutcome_FailureWithHediff" MayRequire="Ludeon.RimWorld.Biotech"> <chance>0.03</chance> <failedHediff>Sterilized</failedHediff> <applyToRecipes> <li MayRequire="Ludeon.RimWorld.Biotech">ImplantIUD</li> <li MayRequire="Ludeon.RimWorld.Biotech">RemoveIUD</li> </applyToRecipes> <failure>true</failure> <totalDamage>10</totalDamage> <applyEffectsToPart>true</applyEffectsToPart> <letterLabel>Surgery failed on {PATIENT_labelShort}: Sterilized</letterLabel> <letterText>{SURGEON_labelShort} has failed while operating on {PATIENT_labelShort} ({RECIPE_label}), leaving {PATIENT_objective} sterile.</letterText> </li> <!-- irrelevant nodes omitted --> </outcomes> <!-- irrelevant nodes omitted --> </SurgeryOutcomeEffectDef>	`MayRequire` is used in the list of possible surgery outcomes to add the possibility of accidentally sterilizing the patient as a result of a surgery failure. Note that the use of `MayRequire` on the list nodes of the `<applyToRecipes>` is technically unnecessary as the entire outcome node would not have loaded without Biotech active.
<AlienRace.ThingDef_AlienRace Name="ARR_RaceBase" ParentName="HumanRace" Abstract="True"> <!-- irrelevant nodes omitted --> <comps> <li Class="ARimReborn.CompProperties_ClassUser" MayRequire="Aelanna.ARimReborn.ClassesAndJobs" /> </comps> <inspectorTabs> <li MayRequire="Aelanna.ARimReborn.ClassesAndJobs">ARimReborn.ITab_Pawn_Classes</li> </inspectorTabs> </AlienRace.ThingDef_AlienRace>	`MayRequire` can be used to omit entire code components. In this modded example, both a ThingComp and an inspector tab are only added if a specific sub-mod is loaded.
<Operation Class="PatchOperationSequence"> <operations> <li Class="PatchOperationAdd" MayRequire="Ludeon.Rimworld.Biotech"> <!-- Only runs if Biotech is active --> <xpath>Defs/ThingDef[defName="MechGestator"]/recipes<xpath> <value> <li>MyCustomMech</li> </value> </li> <li Class="PatchOperationAdd" MayRequire="MyProject.OtherModPackageId"><!-- Only runs if the specific mod is active --> <xpath>Defs/ThingDef[defName="OtherModWorkbench"]/recipes</xpath> <value> <li>MyCustomResource</li> </value> </li> </operations> </Operation>	`MayRequire` can be used in lieu of PatchOperationFindMod in a PatchOperationSequence. Warning: PatchOperationSequence can obfuscate errors, so it is strongly recommended that you individually test patches first before you place them in a sequence. Please see PatchOperations for more information.

Stat Blocks

MayRequire can be used by any StatModifier list, which includes all statBases, statOffsets, statFactors, and equippedStatOffsets nodes:

XML Description

<ThingDef ParentName="ApparelMakeableBase">
  <defName>Apparel_Duster</defName>
  
  <!-- irrelevant tags omitted -->
  
  <equippedStatOffsets>
    <SlaveSuppressionOffset MayRequire="Ludeon.RimWorld.Ideology">-0.05</SlaveSuppressionOffset>
  </equippedStatOffsets>
  
  <!-- irrelevant tags omitted -->
</ThingDef>

MayRequire is used by several vanilla apparel ThingDefs to apply stats that are only relevant to DLCs, such as the SlaveSuppressionOffset stat from Ideology.

<ThingDef Name="TorchLamp" ParentName="BuildingBase">
  <defName>TorchLamp</defName>
  <label>torch lamp</label>
  
  <!-- irrelevant nodes omitted -->
  
  <statBases>
    <MaxHitPoints>75</MaxHitPoints>
    <WorkToBuild>100</WorkToBuild>
    <Flammability>0</Flammability>
    <MeditationFocusStrength>0.0</MeditationFocusStrength>
    <StyleDominance MayRequire="Ludeon.RimWorld.Ideology">5</StyleDominance>
  </statBases>
  
  <!-- irrelevant nodes omitted -->
  
</ThingDef>

MayRequire is used by several vanilla buildings such as the torch lamp to determine how much that particular building influences the overall style of the room it is in. This is also an Ideology feature.

Optional Defs

MayRequire can be used to conditionally load entire Defs. This is far easier to use than the prior option of using PatchOperations to inject new Defs.

XML Description

<ThingDef MayRequire="Ludeon.RimWorld.Ideology" ParentName="Brazier">
  <defName>DarklightBrazier</defName>
  <label>darklight brazier</label>
  <description>A specially treated brazier that illuminates its surroundings with darklight and creates heat. These satisfy royal brazier requirements.</description>
  
  <!-- irrelevant content omitted -->

</ThingDef>

MayRequire is used to activate Royalty's darklight brazier stat if Ideology is also loaded.

<StatDef ParentName="MeditationFocusBase" MayRequireAnyOf="Ludeon.RimWorld.Royalty,Ludeon.RimWorld.Biotech">
  <defName>MeditationFocusGain</defName>
  <label>meditation psyfocus gain</label>
  
  <!-- irrelevant content omitted -->
  
</StatDef>

MayRequireAnyOf is used to activate the MeditationFocusGain stat if either Royalty or Biotech is loaded.

<ThingDef ParentName="ApparelMakeableBase" MayRequireAnyOf="Ludeon.RimWorld.Royalty,Ludeon.RimWorld.Biotech">
  <defName>Apparel_Cape</defName>
  <label>cape</label>
  
  <!-- irrelevant content omitted -->
  
</ThingDef>

MayRequireAnyOf is used to activate the Cape apparel if either Royalty or Biotech is loaded.

Miscellaneous

The following are specific, non-standard usages of MayRequire. Some of these are technically lists with special parsing, some are fields that were coded specifically to accept the MayRequire attribute.

XML	Description
<BiomeDef> <defName>TemperateForest</defName> <wildPlants> <Plant_Grass>5.0</Plant_Grass> <Plant_GrayGrass MayRequire="Ludeon.RimWorld.Biotech">2</Plant_GrayGrass> <Plant_TallGrass>2.0</Plant_TallGrass> <Plant_Brambles>1.0</Plant_Brambles> <Plant_Ripthorn MayRequire="Ludeon.RimWorld.Biotech">0.8</Plant_Ripthorn> <!-- many entries omitted --> </wildPlants> <pollutionWildAnimals MayRequire="Ludeon.RimWorld.Biotech"> <Toxalope MayRequire="Ludeon.RimWorld.Biotech">0.4</Toxalope> <WasteRat MayRequire="Ludeon.RimWorld.Biotech">0.1</WasteRat> <!-- many entries omitted --> </pollutionWildAnimals> <!-- irrelevant nodes omitted --> </BiomeDef>	`MayRequire` is used in `BiomeDef` entries to specify wild plants and animals that are only present in DLCs.
<FactionDef ParentName="FactionBase"> <defName>Mechanoid</defName> <label>mechanoid hive</label> <pawnGroupMakers> <li> <!-- All types--> <kindDef>Combat</kindDef> <commonality>100</commonality> <options> <Mech_Scyther>10</Mech_Scyther> <Mech_Pikeman>10</Mech_Pikeman> <Mech_Lancer>10</Mech_Lancer> <Mech_CentipedeBlaster>10</Mech_CentipedeBlaster> <Mech_Militor MayRequire="Ludeon.RimWorld.Biotech">20</Mech_Militor> <Mech_Centurion MayRequire="Ludeon.RimWorld.Biotech">2</Mech_Centurion> <Mech_Warqueen MayRequire="Ludeon.RimWorld.Biotech">1</Mech_Warqueen> <Mech_Apocriton MayRequire="Ludeon.RimWorld.Biotech">1</Mech_Apocriton> </options> </li> <!-- many other nodes omitted --> </pawnGroupMakers> <!-- many other nodes omitted --> </FactionDef>	`MayRequire` is used by official content `FactionDef` entries to specify `PawnKindDef` types that only exist in DLCs.
<FactionDef ParentName="FactionBase" Name="OutlanderFactionBase" Abstract="True"> <disallowedMemes> <li MayRequire="Ludeon.RimWorld.Ideology">Structure_Animist</li> <li MayRequire="Ludeon.RimWorld.Ideology">Nudism</li> <li MayRequire="Ludeon.RimWorld.Ideology">Blindsight</li> </disallowedMemes> <structureMemeWeights> <Structure_TheistEmbodied MayRequire="Ludeon.RimWorld.Ideology">1</Structure_TheistEmbodied> <Structure_TheistAbstract MayRequire="Ludeon.RimWorld.Ideology">2</Structure_TheistAbstract> <Structure_Ideological MayRequire="Ludeon.RimWorld.Ideology">1</Structure_Ideological> <Structure_Archist MayRequire="Ludeon.RimWorld.Ideology">1</Structure_Archist> <Structure_OriginChristian MayRequire="Ludeon.RimWorld.Ideology">1</Structure_OriginChristian> <Structure_OriginIslamic MayRequire="Ludeon.RimWorld.Ideology">1</Structure_OriginIslamic> <Structure_OriginHindu MayRequire="Ludeon.RimWorld.Ideology">1</Structure_OriginHindu> <Structure_OriginBuddhist MayRequire="Ludeon.RimWorld.Ideology">1</Structure_OriginBuddhist> </structureMemeWeights> <!-- many nodes omitted --> </FactionDef>	`MayRequire` must be used for meme and precept references in `FactionDef` entries, as they only exist if Ideology is loaded.
<FactionDef ParentName="FactionBase" Name="OutlanderFactionBase" Abstract="True"> <xenotypeSet> <xenotypeChances> <Hussar MayRequire="Ludeon.RimWorld.Biotech">0.05</Hussar> <Dirtmole MayRequire="Ludeon.RimWorld.Biotech">0.05</Dirtmole> <Genie MayRequire="Ludeon.RimWorld.Biotech">0.025</Genie> <Neanderthal MayRequire="Ludeon.RimWorld.Biotech">0.025</Neanderthal> </xenotypeChances> </xenotypeSet> <!-- many nodes omitted --> </FactionDef>	`MayRequire` must be used for xenotype references in `FactionDef` entries, as they only exist if Biotech is loaded.
<PawnKindDef Abstract="True" Name="BasePlayerPawnKind"> <race>Human</race> <apparelIgnorePollution MayRequire="Ludeon.RimWorld.Biotech">true</apparelIgnorePollution> <!-- many nodes omitted --> </PawnKindDef>	`MayRequire` is used by `PawnKindDef` for the `apparelIgnorePollution` node, which is only applicable if Biotech is loaded.
<LifeStageDef ParentName="HumanlikeAdolescent"> <defName>HumanlikeBaby</defName> <label>baby</label> <thinkTreeMainOverride MayRequire="Ludeon.RimWorld.Biotech">HumanlikeBaby</thinkTreeMainOverride> <thinkTreeConstantOverride MayRequire="Ludeon.RimWorld.Biotech">HumanlikeBabyConstant</thinkTreeConstantOverride> <!-- many nodes omitted --> </LifeStageDef> <LifeStageDef Name="LifeStageHumanlikeChild" ParentName="HumanlikeAdolescent"> <defName>HumanlikeChild</defName> <label>child</label> <workerClass MayRequire="Ludeon.RimWorld.Biotech">LifeStageWorker_HumanlikeChild</workerClass> <!-- many nodes omitted --> </LifeStageDef>	`MayRequire` is used for think tree override and worker classes in `LifeStageDef` entries for functionality related to children and growth in Biotech.