Adding a New Gas

This page will guide you through adding your own custom gas to the game using the framework. Code snippets and screenshots shown are from my knockout gas mod.

Important

This guide assumes you know the the basics of RimWorld XML modding, like what folder structure to follow and how Defs work. If you aren't at that stage yet, check out some modding tutorials on the RimWorld wiki.

1. Adding The Framework

Obviously your mod requires this framework in order for the custom gas to work. So be sure to include it in the <modDependencies> and <loadAfter> nodes of the About.xml file.

<!-- About/About.xml -->
<!-- https://rimworldwiki.com/wiki/Modding_Tutorials/About.xml -->
<?xml version="1.0" encoding="utf-8"?>
<ModMetaData>
	<name>Knockout Gas</name>
	<packageId>NachoToast.KnockoutGas</packageId>
	<author>NachoToast</author>
	<description>Create knockout gas, which causes biological lifeforms to slowly become unconscious.</description>
	<supportedVersions>
		<li>1.5</li>
	</supportedVersions>
    <modDependencies>
        <li>
            <packageId>NachoToast.SCGF</packageId>
            <displayName>Simple Custom Gas Framework</displayName>
            <steamWorkshopUrl>steam://url/CommunityFilePage/2999444522</steamWorkshopUrl>
            <downloadUrl>https://github.com/NachoToast/SimpleCustomGasFramework/releases/latest</downloadUrl>
        </li>
    </modDependencies>
	<loadAfter>
		<li>NachoToast.SCGF</li>
	</loadAfter>
</ModMetaData>

2. Creating the GasDef

Now you can make any number of SCGF.GasDef defs, these will be detected by the framework when the game launches. They should contain a <label> and <color> at the very minimum.

<!-- 1.5/Defs/GasDefs/KnockoutGas.xml -->
<?xml version="1.0" encoding="utf-8"?>
<Defs>
    <SCGF.GasDef ParentName="GasBase">
        <defName>KnockoutGas</defName>
        <label>knockout gas</label>
        <color>(0, 140, 142)</color>
        <actions>
            <li Class="SCGF.Actions.ApplyHediff">
                <hediff>Anesthetic</hediff>
            </li>
        </actions>
    </SCGF.GasDef>
</Defs>

The ParentName="GasBase" attribute means the gas inherits properties from the GasBase GasDef, like only applying to organic pawns and being stopped by gas masks.

Tip

If you desire different mechanics (e.g. the gas applying to mechanoids instead of organic pawns), keep inheriting from GasBase and disable inheritance on relevant subnodes (learn more).

A full list of properties you can give your GasDef can be found on the GasDef Properties wiki page, I recommended at least having a brief look through them.

Now you can test that your custom gas is working simply by launching RimWorld, the debug log should include a message indicating how many custom gases it found.

You can also see how the gas looks and behaves by using the "Add gas..." debug action on a map:

3. Utilizing the Gas

Now that your gas exists, it's time to do something with it!

The following 3 steps will spawn in your custom gas via explosions. In order for this to work, you need a add a DamageDef.

<!-- 1.5/Defs/DamageDefs/Damages_Misc.xml -->
<?xml version="1.0" encoding="utf-8"?>
<Defs>
    <!-- Mostly copied from RimWorld's Smoke DamageDef -->
    <DamageDef>
        <defName>NachoToast_KnockoutGasSmoke</defName>
        <label>knockout gas</label>
        <canInterruptJobs>false</canInterruptJobs>
        <makesBlood>false</makesBlood>
        <defaultDamage>0</defaultDamage>
        <explosionCellFleck>BlastExtinguisher</explosionCellFleck>
        <explosionColorEdge>(0, 140, 142, 13)</explosionColorEdge>
        <harmsHealth>false</harmsHealth>
        <soundExplosion>Explosion_Smoke</soundExplosion>
        <combatLogRules>Damage_Smoke</combatLogRules>
        <modExtensions>
            <li Class="SCGF.CustomGasExtension">
                <gasDef>KnockoutGas</gasDef>
            </li>
        </modExtensions>
    </DamageDef>
</Defs>

The important parts here are <explosionColorEdge>, which should generally be the GasDef colour with some added transparency (the 4th number, I find 13 to be a good value), and <modExtensions>, which tells the framework what custom gas type to use.

Now the DamageDef is setup, you can reference it in the steps below.

3a. IED Trap

<!-- 1.5/Defs/ThingDefs_Buildings/Buildings_Security.xml -->
<?xml version="1.0" encoding="utf-8"?>
<Defs>
    <!-- Mostly copied from RimWorld's TrapIED_Smoke ThingDef -->
    <ThingDef ParentName="TrapIEDBase">
        <defName>NachoToast_TrapIED_KnockoutGas</defName>
        <label>IED Knockout gas trap</label>
        <description>A pair of knockout gas shells connected to a trigger which detonates on touch or bullet impact. Since it is hidden in the surrounding terrain, it cannot be placed adjacent to other traps. Animals can sense these when calm.</description>
        <descriptionHyperlinks>
            <HediffDef>Anesthetic</HediffDef>
        </descriptionHyperlinks>
        <graphicData>
            <texPath>Things/Building/Security/IEDSmoke</texPath>
        </graphicData>
        <uiOrder>47</uiOrder>
        <costList>
            <Shell_Smoke>2</Shell_Smoke>
        </costList>
        <comps>
            <li Class="CompProperties_Explosive">
                <explosiveRadius>8.6</explosiveRadius>
                <explosiveDamageType>NachoToast_KnockoutGasSmoke</explosiveDamageType>
                <startWickHitPointsPercent>0.2</startWickHitPointsPercent>
                <wickTicks>15</wickTicks>
                <startWickOnDamageTaken>
                    <li>Bullet</li>
                    <li>Arrow</li>
                    <li>ArrowHighVelocity</li>
                </startWickOnDamageTaken>
            </li>
        </comps>
        <specialDisplayRadius>8.6</specialDisplayRadius>
        <researchPrerequisites>
            <li>GasOperation</li>
        </researchPrerequisites>
    </ThingDef>
</Defs>

Tip

You can test the IED explosion using the "T: 300 damage" debug action!

3b. Mortar Shell

<!-- 1.5/Defs/ThingDefs_Misc/Items_Resource_Shell.xml -->
<?xml version="1.0" encoding="utf-8"?>
<Defs>
    <!-- Mostly copied from RimWorld's Shell_Smoke ThingDef -->
    <ThingDef ParentName="MakeableShellBase">
        <defName>NachoToast_Shell_KnockoutGas</defName>
        <label>knockout gas shell</label>
        <description>A shell that releases a cloud of knockout gas when detonated. Can be fired from mortars or installed as a trap. Explodes when damaged.</description>
        <descriptionHyperlinks>
            <HediffDef>Anesthetic</HediffDef>
        </descriptionHyperlinks>
        <possessionCount>2</possessionCount>
        <graphicData>
            <texPath>Things/Item/Resource/Shell/Shell_Smoke</texPath>
            <graphicClass>Graphic_StackCount</graphicClass>
        </graphicData>
        <comps>
            <li Class="CompProperties_Explosive">
                <explosiveDamageType>NachoToast_KnockoutGasSmoke</explosiveDamageType>
                <explosiveRadius>11</explosiveRadius>
                <wickTicks>30~60</wickTicks>
            </li>
        </comps>
        <projectileWhenLoaded>NachoToast_Bullet_Shell_KnockoutGas</projectileWhenLoaded>
        <costList>
            <Steel>10</Steel>
            <MedicineHerbal>5</MedicineHerbal>
        </costList>
        <costListForDifficulty>
            <difficultyVar>classicMortars</difficultyVar>
            <costList>
                <Steel>30</Steel>
                <MedicineHerbal>5</MedicineHerbal>
            </costList>
        </costListForDifficulty>
        <recipeMaker>
            <researchPrerequisites>
                <li>Mortars</li>
                <li>GasOperation</li>
            </researchPrerequisites>
            <displayPriority>130</displayPriority>
        </recipeMaker>
    </ThingDef>

    <!-- Mostly copied from RimWorld's Bullet_Shell_Smoke ThingDef -->
    <ThingDef ParentName="BaseBullet">
        <defName>NachoToast_Bullet_Shell_KnockoutGas</defName>
        <label>knockout gas shell</label>
        <graphicData>
            <texPath>Things/Projectile/ShellSmoke</texPath>
            <graphicClass>Graphic_Single</graphicClass>
            <shaderType>TransparentPostLight</shaderType>
        </graphicData>
        <thingClass>Projectile_Explosive</thingClass>
        <projectile>
            <damageDef>NachoToast_KnockoutGasSmoke</damageDef>
            <speed>41</speed>
            <explosionRadius>7.2</explosionRadius>
            <flyOverhead>true</flyOverhead>
            <soundHitThickRoof>Artillery_HitThickRoof</soundHitThickRoof>
            <soundExplode>Explosion_Smoke</soundExplode>
            <soundImpactAnticipate>MortarRound_PreImpact</soundImpactAnticipate>
            <soundAmbient>MortarRound_Ambient</soundAmbient>
        </projectile>
    </ThingDef>
</Defs>

3c. Launcher

Tip

This is also where you would put grenades.

<!-- 1.5/Defs/ThingDefs_Misc/Weapons/RangedIndustrial.xml -->
<?xml version="1.0" encoding="utf-8"?>
<Defs>
    <!-- Mostly copied from RimWorld's Gun_SmokeLauncher ThingDef -->
    <ThingDef ParentName="BaseHumanMakeableGun">
        <defName>NachoToast_Gun_KnockoutGasLauncher</defName>
        <label>knockout gas launcher</label>
        <description>A wide-barreled knockout gas shell launcher. The shell will upon impact release a cloud of knockout gas.</description>
        <descriptionHyperlinks>
            <HediffDef>Anesthetic</HediffDef>
        </descriptionHyperlinks>
        <graphicData>
            <texPath>Things/Item/Equipment/WeaponRanged/SmokeLauncher</texPath>
            <graphicClass>Graphic_Single</graphicClass>
        </graphicData>
        <soundInteract>Interact_Rifle</soundInteract>
        <generateCommonality>0.3</generateCommonality>
        <weaponClasses>
            <li>RangedHeavy</li>
        </weaponClasses>
        <statBases>
            <WorkToMake>30000</WorkToMake>
            <Mass>3.4</Mass>
            <RangedWeapon_Cooldown>4.5</RangedWeapon_Cooldown>
        </statBases>
        <costList>
            <Steel>75</Steel>
            <ComponentIndustrial>4</ComponentIndustrial>
            <MedicineHerbal>20</MedicineHerbal>
        </costList>
        <weaponTags Inherit="False">
            <li>GrenadeSmoke</li>
        </weaponTags>
        <recipeMaker>
            <skillRequirements>
                <Crafting>4</Crafting>
            </skillRequirements>
            <researchPrerequisite>GasOperation</researchPrerequisite>
            <displayPriority>471</displayPriority>
        </recipeMaker>
        <verbs>
            <li>
                <verbClass>Verb_Shoot</verbClass>
                <hasStandardCommand>true</hasStandardCommand>
                <defaultProjectile>NachoToast_Bullet_KnockoutGasLauncher</defaultProjectile>
                <warmupTime>3.5</warmupTime>
                <range>23.9</range>
                <forcedMissRadius>1.9</forcedMissRadius>
                <burstShotCount>1</burstShotCount>
                <soundCast>Shot_IncendiaryLauncher</soundCast>
                <soundCastTail>GunTail_Medium</soundCastTail>
                <muzzleFlashScale>14</muzzleFlashScale>
                <targetParams>
                    <canTargetLocations>true</canTargetLocations>
                </targetParams>
            </li>
        </verbs>
        <tools>
            <li>
                <label>stock</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>

    <!-- Mostly copied from RimWorld's Bullet_SmokeLauncher ThingDef -->
    <ThingDef ParentName="BaseBullet">
        <defName>NachoToast_Bullet_KnockoutGasLauncher</defName>
        <label>knockout gas launcher shell</label>
        <graphicData>
            <texPath>Things/Projectile/LauncherShot</texPath>
            <graphicClass>Graphic_Single</graphicClass>
            <shaderType>TransparentPostLight</shaderType>
            <color>(84,135,113)</color>
        </graphicData>
        <thingClass>Projectile_Explosive</thingClass>
        <projectile>
            <speed>40</speed>
            <damageDef>NachoToast_KnockoutGasSmoke</damageDef>
            <explosionRadius>2.4</explosionRadius>
            <ai_IsIncendiary>true</ai_IsIncendiary>
            <arcHeightFactor>0.2</arcHeightFactor>
            <shadowSize>0.6</shadowSize>
            <screenShakeFactor>0.5</screenShakeFactor>
        </projectile>
    </ThingDef>
</Defs>