Custom Abilities

Creating custom abilities is harder than creating a custom class, but it is very gratifying. However, I have not yet fully mastered the process, so there may be errors in this guide. I'll try to mark potential issues.

This guide is going to assume you will use no C# whatsoever.

For examples of custom abilities, look at Kure's Class Expansion Pack, or at my own Blue Mage custom class. Kure only uses vanilla Rimworld + RWoM, my Blue Mage also uses the frameworks VEF and MoHAR, which allows me to do some interesting things without any coding.

As with anything XML, I recommend you download Notepad++ and work with it. You can also use an XML validator to check your XML formatting. I strongly recommend using Notepad++ to perform a text search on all files of a folder, to look at every single time something you are curious about is used. For vanilla Rimworld, there is such a database at this link. The software Everything is also handy, as it finds files instantly, like a good version of Windows's Search.

You start the process by copying an existing ability that mostly does what you want.

A custom ability has four things: an **ability def** (which contains its name, description, whether it's for mages or fighters, icon, cost), which contains a **verb** (which is what defines what the ability does), which shoots a **projectile** (which is somewhat limited in what can be done with it) and a **power def** (which defines the max level, upgrades, and leveling cost of the ability).

On top of that, you can make your spells apply hediffs (things like implants and diseases in vanilla, which you see in your pawn's health tab), which is one way to differentiate them from normal abilities, mental states, and spawn things.

### Ability Def

The easy part. You can see here a list of tags used by RWoM abilities, although this does not cover all of them (because abilities are also partially defined by JecsTools and vanilla). You need to change the following:

- in the very first tag, ParentName="..." should be either BaseMagicAbility or BaseMightAbility, depending on whether this is a mage spell or fighter spell.

- defName should be the internal name for your ability. Typically, it's TM\_AbilityNameInCamelCase. It must not be the same name as anything else. Each upgrade level should have a different defName.

- label is the visible name for your ability.

- uiIconPath is where the graphic for your ability's icon is. In the base mod, it's all in the UI folder. I recommend you do the same.

- description is the description for your ability, readable when hovering on the ability's gizmo and in the upgrade menu.

- manaCost/staminaCost is the ability's cost. You can only use one Cost tag. You can also use chiCost if your class uses chi and bloodCost if your class uses blood.

- efficiencyReductionPercent should be the percentage of the ability's cost that is reduced by its efficiency upgrade, but I didn't get that to work.

- weaponDamageFactor adds a percentage of the current weapon's average damage to the ability. My understanding is that it uses a melee weapon's average damage and a ranged weapon's projectile damage. This is only relevant for a few verbs (if a verb didn't use weaponDamageFactor, it won't care about it).

- requiredWeaponsOrCategories forces certain weapons to be equipped to use this ability. For a list of which weapon belongs to which category, in RWOM, look at the WeaponCategoryDef. You can probably add your own weapon to a category, or even create a category. The tag is optional.

- canCopy defines whether the ability can be copied by Legion or Mimic.

- learnChance defines the chance to randomly learn the ability when the class is first learnt.

- learnItem sets the name of the item that teaches the ability, if you want the ability to require a scroll.

- shouldInitialize is whether the ability should have an icon appear like other spells. It should always be true, unless you want the ability to be unusable.

### Verb

In vanilla, the best-known verb is called Verb\_Shoot: it's what makes ranged weapons shoot projectiles.

A verb uses one of the many actual C# spells coded by Torann to do a thing. The basic verb is AbilityUser.Verb\_UseAbility (and, built on top with minimal changes, BLOS and SB); when these verbs are used, it's typically the projectile that is doing the heavy lifting. Verbs that are not these three are relatively hardcoded; therefore, unless you want to create an ability that is just "ability X but it's AoE/but it has different values for costs or damage/but it applies a hediff", you're going to stick to these three.

A special verb that was not coded by Torann, and is used in the FieldMedic abilities, is called ApplyRandomHediffFromList. It takes different parameters from every other verb in the mod, but it's very well commented in the original file. It lets you apply hediffs in very interesting ways.

Generally, I use SB or BLOS. The only difference is that SB can be used with a shield belt, and BLOS does not require line of sight and do the interesting things with hediffs and projectiles. In the verb parameters, you define the range, warmup time, cooldown, projectile, valid targets (targetParams is the exact same as in vanilla, look at EpicGuru's documentation, linked above, for the list of valid targetParams), sound when cast, and a bunch of useless things.

You can also add a warmupEffecter: an effecter that plays while the spell is getting "aimed". This requires an EffecterDef, which works just like in vanilla. If you are feeling graphically fancy, this can be very pretty (surrounding your caster in runes while charging a spell, for instance). Similarly, you can use the tags the Diabolus's weapon uses to have a mote on the target or a line between caster and target.

On top of that, you can apply hediffs with abilities. Hediffs are only applied to the target if the projectile hits the target; otherwise, the hediff is applied to the caster. This means that an explosive projectile, if targeted on the ground, applies the hediff to the caster, but applies its hediff to the target if targeted on a pawn. If you want to apply hediffs to several enemies at once, either make a damageDef that applies a hediff with severity proportional to damage, or use AoE targeting to affect several pawns at once (in which cast it's not an explosive). You can apply several hediffs, with a given chance, and a given severity. You cannot apply hediffs on specific body parts that way. Look at Abilities\_TMagic\_Apothecary.xml, Herbal Clarity, for an example.

Applying hediffs is extremely useful because it lets you tie abilities with frameworks that give new possibilities to hediffs.

AoE targeting lets you target several pawns in an AoE. Annoyingly, this may fail to shoot things that do not belong to an enemy faction; as such, an AoE targeted ability will fail to hit manhunting animals, for instance. You should turn on friendlyFire if you want the ability to target every pawn in its radius. Look at Abilities\_TMagic\_Standalone.xml, Heat Shield, for an example.

### Projectile

The meat of most spells. You cannot use a vanilla thingClass (the basic thingClass is AbilityUser.Projectile\_Ability, or AbilityUser.Projectile\_AbilityLaser to make something that looks like a laser) for your projectile, and a lot of projectile parameters (spawning things on explosion, spawning filth on explosion, that sort of thing) are ignored.

However, the damageDef, damageAmountBase, speed, and graphicData are not ignored. You can also have an explosion radius of your choice for explosives.

If you want an invisible projectile that does no damage (often the case if you want to make a spell that applies a hediff), you can use Projectile\_Default.

Note that, if your class does not have stamina, you cannot use a projectile class used by a stamina-using class; similarly, if your class does not have mana, you cannot use a projectile class used by a mana-using class (as the underlying C# is going to fail to find magical/physical stats, basically) . For instance, if you make a custom mage and want to make an explosive projectile, you cannot use the Super Soldier's grenade, you would have to use Arcane Bolt or Fireball.

You can use the Buckshot verb to shoot pretty much any projectile (but it will shoot many projectiles at once). It seems to work even for classes without stamina.

### Power Def

The powerDef makes an ability learnable and upgradeable. Look at the CustomDefs/CustomPowerDefs.xml file for examples.

You will list every level of the ability in the powerDef, so that the game can recognize these are related and upgrade into each other.

Upgrades are verb based and are going to do the same thing as the original verb. You can change the upgrade's tooltip by adding a different languageData for it, which is really easy. Go to Languages/English/Keyed/TM\_English for examples.

If you want to make an ultimate spell, or one that requires a scroll to be unlocked, you need to add <requiresScroll>true</requiresScroll> to the powerDef.