Well, congratulations, you’ve decided to make a patch for (insert mod of choice here), and boy—you’re really in for it now.

If you’re anything like me, Combat Extended has gotten its hooks into you; it doesn’t matter what was. Maybe you were enticed by the fast and lethal combat, or perhaps you liked the ammo system, or maybe you just liked the idea of creating your own personal military industrial complex as you brought an entire planet to heel. Regardless, you’re playing Combat Extended now, and the odds are decent that it will irreversibly ruin vanilla Rimworld combat for you. So, there’s that to be grateful for.

At any rate, you’ve almost certainly realized that there are quite a few mods that don’t work alongside Combat Extended. To some extent, this is unavoidable—Combat Extended is an extremely complex mod that makes Rimworld do some pretty incredible stuff, but you can’t make an omelet without knocking a few eggs off of walls, or however that idiom goes. But a compatibility patch makes all the difference; it bridges the gap between mods written for vanilla Rimworld and the custom mechanics and systems of Combat Extended.

This guide will walk you through that process of patching a typical mod as simply as possible; I’m going to act like you’re a complete idiot (because let’s be real here...) who’s never even accidentally opened their Rimworld directory. So, pour yourself a tall glass of the beverage of choice and get reading.

Note: This is a mod for patching a fairly standard mod to work with Combat Extended, such as a weapon pack, a collection of clothing, or a custom animal or faction. While these categories cover the lion’s share of mods that you’d prospectively want to make a patch for, there are almost assuredly mods out there with more complex Assembly aspects that would be more complicated to mesh with Combat Extended, but those are outside the scope of this guide.

First, we need to lay a groundwork for the task at hand; collect some basic tools, establish some basic knowledge, stuff like that. Note: If you’re already feeling pretty comfortable with XML and XPathing, feel free to skip to the next section.

The Tools

Fundamentally, you really only need four things to create a patch:

• A text-editing software of your choice (I happen to use Notepad++) [notepad-plus-plus.org]
• A copy of Rimworld
  
• A copy of Combat Extended
  
• A copy of the mod you want to patch

There are other tools and resources that would certainly be helpful (which I’ve linked throughout this guide), but these are the bare necessities.

The Gist of XML
If you open up your Rimworld directory and flip through the folders, you’ll find a lot of files in the eXtensible Markup Language (XML) format. I won’t delve into the ‘how’s and ‘why’s, but we just need to nail down a few basic principles about XML within the context of Rimworld before we move on:

• XML is just data – an XML file doesn’t actually do anything; it’s just a collection of characteristics (such as hit points, flammability, and appearance) that other code works with.
  
• XML is hierarchal - This data can be passed down from a “Parent” to a “Child,” giving the “Child” the same characteristics (unless they’re intentionally suppressed). This is useful for creating templates or “Bases” for items that all share some basic characteristics with one another, such as clothing for example, without the need for lots of duplication.
  
• Defs – The characteristics of almost everything you see (furniture, weapons, creatures, factions, etc.) and experience (scenarios, sounds, etc.) within Rimworld is defined by something called a “Def.” There are various types—SoundDefs, ThingDefs, PawnDefs, and a number of others, but they call fundamentally do the same thing. You can think of these simply as lists of characteristics that define how things behave.

The game then uses programming in C# (C-Sharp) to define what characteristics each kind of “Def” is allowed to have and what their function in-game is, but the details of that are beyond the scope of this guide.

For more information and some good examples, check out the Rimworld wiki tutorial.[rimworldwiki.com]

The Gist of XPath
XPath is the language/mechanism that makes patching possible. It allows you to target specific nodes and tags (in effect, individual characteristics) and manipulate them in a variety of ways within an XML file. This is useful if we can’t edit a file directly, or when we want to do so conditionally—such as based on whether or not a particular mod is active.

Some more resources that may be useful:

• A more comprehensive overview of XPathing’s role in patching[ludeon.com].
  
• A list of XPath syntax and structuring[www.w3schools.com].
  
• A partial list of PatchOperations[rimworldwiki.com].
  
  All are useful and good to know, but none are strictly necessary.
  
  If you’ve ever opened Windows Explorer to look for a file, you should immediately notice the bulk of xpathing system looks quite similar to a typical folder structure. So, once we've identified the Def we want to change with xpath, we can--in effect--follow the "path" as it looks for the specific content the patch is targeting. This can be as particular as an individual characteristic or as broad as an entire Def.
  
  Note: Xpath operations are cap sensitive! If you aren't careful about this, you may find yourself tearing your hair out over a patch that isn't working for want of a single capital letter.

First things first; look around and see if the mod you want to patch already has a compatibility patch floating out there somewhere. Check the Steam workshop, check the Combat Extended discord, check the Ludeon forums. You did already? You’re positive? And you didn’t find anything? What about an outdated patch? It’s a lot quicker and easier to update an outdated compatibility patch than it is to make one from scratch.

Alright, well I’ve got some good news for you; making a Combat Extended patch is 90% copy-paste. The other 10% is renaming things and changing stats. The caveat to that is that it’s important you do the copy-pasting carefully and correctly, or you’ll just find yourself left with the same mistakes to fix a whole bunch of times.

The actual task of making a patch is really simple—seriously. All you really need to do is insert a few custom characteristics that Combat Extended adds (which characteristics exactly vary based on what kind of thing you’re patching), and making sure there’s no overlap. That’s it.

There's a bit of stat tweaking to be done later on, but that's fairly straight forward as well, and is largely dictated by a set of sheets maintained by the Combat Extended team to keep content mostly balanced across mods.

In some instances, things will have Parents that have already been patched by Combat Extended. Take care to review other patches that may affect what you're working on before getting started.

For references on what values to use, check out the 'Core' Combat Extended patches, they’re extremely useful as reference material. In the following sections, I’ve annotated several sample patches for various categories, providing additional explanation below each image.

As with any other patched content, when trying to generate stats, the best thing to do is either use one of the sheets (if available) or to use other, similar items for reference.

• <Bulk> - This is simply an abstract quantity that sums up how much space an item takes in someone's inventory while carrying it. Consider not only the volume, but also the unwieldiness of an item while equipped with it or being stored in an inventory. Almost all items in the game have a <bulk> stat, and it defaults to ‘1’ for items without a specified value.
  
• <wornBulk> - Similar to the above, this is the bulk felt by a pawn wearing this piece of apparel, rather than carrying it, and its typically a fraction of the item’s <bulk>. For items without a specified value, it defaults to ‘1’.
  
• <CarryWeight> - This affects a pawn’s maximum carry weight when worn. You’ll generally see this on load-bearing gear such as backpacks and chest rigs, but more mundane items with pockets—such as pants or jackets—may also have a small value.
  
• <CarryBulk> - Often seen together with <CarryWeight>, this affects a pawn’s maximum carry volume when worn. You’ll generally see this on load-bearing gear such as backpacks and chest rigs, but more mundane items with pockets—such as pants or jackets—may also have a small value.

Additionally, with the changes Combat Extended made to the armor system in version 1.6, there are additional factors to consider.

• <ArmorRating_Sharp> - With the changes to the armor system, sharp armor is now rated in "equivalent to millimeters of Rolled Homogeneous Armor"--essentially, the thickness of a piece of hot-rolled steel. For pieces of armor actually made from steel, this is as simple as inputting the thickness. For other items, it's more practical to review the armor penetrating capabilities of various projectiles and decide which ones you want the armor thick enough to stop. This should be done with care, lest you find yourself wearing medieval-era armor that shrugs off rifle rounds.
  
• <ArmorRating_Blunt> - Similar to the above, blunt armor is now rated units of force--Megapascals. Use your references to decide what other kinds of armor is offers similar protection to and what kinds of attacks you want it to protect from.
  
• <StuffEffectMultiplierArmor> - For apparel made from a material (it will have a name like "wooden" or "cloth" or "devilstrand" [apparel]), it isn't necessary to specify a specific set of armor values. Since all materials have a set blunt and sharp armor rating, you can simply specify a multiplier (this is, in effect, the thickness of the material measured in millimeters), and it will inherit armor stats from the material it is made out of.

Note: Due to the custom combat system, CE has its own components for melee weapons and attacks. This covers all purpose-built and improvised weapons, all unarmed attacks by pawns and animals, and all melee attacks performed with a ranged weapon during close-quarters combat. If left unpatched, the attack will create errors. More useful info can be found on the Combat Extended Github wiki. Check out: to generate stats for attacks.[github.com]

• <capacities> - The nature of the melee attack. Accepted inputs: Blunt, Stab, Cut, Bite, Poke (for blunt thrusts, like the end of a quarterstaff or the muzzle of a rifle), and Scratch (for most clawed strikes).
  
• <power> - An abstraction of how much damage an attack is capable of. For reference, a punch from an unarmed pawn has a power of 6. It’s recommended you use existing weapons and patches for reference to help with balancing.
  
• <armorPenetrationBlunt> - The amount of blunt force (in MPa) an attack causes. As this is important for balance, be sure to use this sheet to calculate the blunt armor penetration value from the attack power and type.[github.com]
  
• <armorPenetrationBlunt> - The amount of armor (measured in mm of RHA) an attack can penetrate. As this is important for balance, be sure to use this sheet to calculate the blunt armor penetration value from the attack power and type.[github.com]
  
• <MeleeCounterParryBonus> - How well a weapon crushes through a foe's attempts to parry. Particularly powerful weapons or those with concentrated mass (like a mace or poleaxe) will have this. This stat goes under statBases. Generated on the Melee Attack sheet.
  
• <MeleeCritChance> - Chance for weapon user to score a critical hit against a foe. For sharp attacks, the critical hit ignores armor. For blunt attacks, a critical hit will stun the target.
  
• <MeleeParryChance> - Chance for a weapon user to parry a foe's attack, allowing them to make an immediate riposte. Generated on the Melee Attack sheet.
  
• <MeleeDodgeChance> - Chance for a weapon user to dodge a foe's attack. Generated on the Melee Attack sheet.

Note: More useful info can be found on the Combat Extended Github wiki.[github.com] Bear in mind that custom races will also likely need their melee attacks patched as well!

• <BaseBodySize> - The general size of a creature, for the purpose of calculating the size of their hitbox. This is their height in meters, divided by their respective bodyshape height multiplier (see below), divided by 1.75.
  
• <bodyShape> - This defines the general stance and shape of a pawn or animal for the purpose of calculating the size of their hitbox. Accepted inputs—with their bodyshape height multiplier---are: Humanoid [1.0], Quadruped [0.5] (for most creatures that don’t walk upright, such as muffalo, centipedes, or wolves), QuadrupedLow [0.25] (for especially small creatures that don’t walk upright, like rabbits or racoons), Serpentine [0.125] (for creatures with long, thin bodies), and BirdLike [0.75] (for creatures with comparatively long necks, like emus or thrumbos).
  
• <li Class="CombatExtended.CompProperties_Suppressable"/> - This enables the suppressed state for the pawn or creature. Add this to anything that is smart enough to be afraid of incoming fire (like a human or reasonably intelligent alien) and doesn’t completely lack a sense of self-preservation (such as a robot or zombie).
  
• <compClass>CombatExtended.CompPawnGizmo</compClass> - Add this to anything that can use a ranged weapon, like intelligent aliens or robots.
  
• <li>CombatExtended.ITab_Inventory</li> - If your creature uses the vanilla "ITab_Pawn_Gear" (that is, broadly speaking, anything that can equip weapons or clothing, or has an inventory), it needs to be replaced with this.
  
• <li Class="CombatExtended.CompProperties_Inventory" /> - Same as the above.

Note: For races that have 'PawnBase' as a Parent, it is usually unnecessary to add inventory support, as Combat Extended patches it into 'PawnBase,' which the custom race will inherit it from.

Note: Combat Extended will not allow a pawn’s loadout to exceed their carrying capacity. If a pawn cannot carry everything proscribed by their loadout, not everything will spawn.

• <primaryMagazineCount> - How many magazines for their primary weapon a particular kind of pawn will spawn with. Remember that both a machine gun’s 50 round drum and a single arrow loaded into a bow both count as a single magazine. This tag can be omitted entirely for pawn types that can only spawn with melee weapons.
  
• <Sidearm> - Allows pawns to spawn with a secondary weapon, usually a handgun or melee weapon, that they will switch to if they run out of ammo. The sub-tags control weapon selection, quality, and how much ammunition they spawn with for ranged sidearms. If you don’t want them to spawn with a sidearm at all, simply omit this tag.
  
• <forcedSidearm> - Same as the above, except it guarantees the pawn will spawn with a sidearm. This is useful for sappers or other kinds of pawns likely to run out of ammo for their primary weapon.
  
• <shieldMoney>, <shieldTags>, <shieldChance> - Controls the kind of shield a pawn will spawn with. Remember that pawns can only use a shield with a one-handed weapon; if they’re equipped with a two-handed weapon and a shield, they won’t be able to attack. If you don’t want a pawn to spawn with a shield at all, simply omit this tag.

Combat Extended’s ranged combat is fundamentally different from vanilla Rimworld at every level. As a result, ranged weapons are more complex and varied to patch than the other items listed above, and they require several different components, depending upon their exact nature. These include:

• Additional components patched in.
  
• Their projectile must be adjusted and if they do not have infinite ammunition or are not a single-use weapon (like a grenade, javelin, or disposable rocket launcher), they must have an ammo set.
  
• Their associated melee attacks to be patched (see Melee Weapons & Attacks). Fortunately, Combat Extended now has a single set of melee stats generated for each category of weapon--handgun, long gun, and launcher. You can simply copy-paste these with the new weapon names.
  
  This section will address each part separately. While there is no particular order they must be patched in, in most cases, all steps must be done.
  
  Weapons
  Check out this spreadsheet for reference/to generate stats for your patched weapons.[docs.google.com]
  
  • <RangedWeapon_Cooldown> - This is generally quite short, compared to vanilla cool down times. This is because Combat Extended incorporates additional aiming time.
    
  • <SightsEfficiency> - An abstract of the quality of a weapon's sights, which affects overall accuracy. While a value of '1' is standard for typical weapons, crude weapons may have a value of 0.7 or worse, while a weapon with a high-quality scope may have far higher. For instance, the vanilla sniper rifle has a SightsEfficiency of '2.6'.
    
  • <ShotSpread> - Higher for weapons that are unstable and/or automatic, such as pistols or SMGs.
    
  • <SwayFactor> - An abstract of general barrel sway from the user. Higher for one-handed or heavy/bulky weapons.
    
  • <recoilAmount> - An abstract of not only recoil amount, but also how difficult it is to manage. Higher caliber weapons obviously have higher recoil, but so do light or one-handed weapons. Single-fire weapons are not affected.
    
  • <Range> - Maximum weapon ranges in general have been greatly increased in Combat Extended. For reference, most pistols have a range of around '12,' shotguns and SMGs around '16,' rifles around '55', and the vanilla sniper rifle a range of '75'.
    
  • <AmmoUser> - Dictates what ammo set the weapon uses, and the magazine size. If you want a weapon to have infinite ammunition, delete this section, but be sure to compensate with longer cooldown times.
    
  • <FireModes> - Dictates what fire modes a weapon can use,and what fire mode the AI will use.
    
  • <weaponTags> - Not only do these tags determine pawn loadouts, in Combat Extended, only weapons with the 'CE_OneHandedWeapon' tag may be used with shields.
  
  Single-use Weapons
  Single-used weapons, such as disposable rocket launchers, or grenades and other throwables, require a bit of extra work in order to make them one-time use, weapon-ammo combinations. This is especially true for explosives. When a weapon of this sort uses the vanilla "BaseGrenadeProjectile" or something that inherits from it, some of this extra work is done for you.
  
  Ammo Sets & Projectiles
  Like in vanilla Rimworld, a projectile is a separate ThingDef from the weapon itself, and dictates all properties relating to damage. That means that while an M2 machine gun turret and a McMillan Tac-50 AMR has different ranges, rates of fire, and accuracy, their projectiles are functionally identical, because both fire .50 caliber BMG rounds.
  
  For non-single use weapons, these the projectile ThingDef is contained in the same file as the ammo set, rather than the weapon. Single-use weapons don't have an ammoset.
  
  When at all possible, existing ammo sets should be used for the weapons you are patching. Not only is this considerably easier than making a new one, it also prevents duplication and unnecessary clutter. Combat Extended already contains a variety of ammo sets, and it’s best to look carefully for one that will suffice before setting off to create a new set. Once again; it’s difficult to overstate the importance of checking through the existing ammunition thoroughly before starting to create a new one.
  
  If you’ve found an existing ammo set to use, congratulations! You’ve saved yourself quite a bit of work.
  
  From this point onward, this section assumes you have not successfully found a suitable existing set, and are therefore creating a new one.
  
  Creating an Ammo Set
  In situations where you are creating your own caliber, this spreadsheet[docs.google.com] can be useful for calculating stats for your projectile, especially when working with a real-world cartridge. In cases where there are no real-world equivalents, it’s best to reference similar ammo types and then adjust balance from there.
  
  Ammo sets are stored under the 'Defs,' as they are separate items entirely. Let's take a look at .303 British, used by the Lee Enfield "survival/bolt-action rifle". It is critically important that everything is spelled correctly, and in the right place. Ammosets can be very tricky to troubleshoot because of this. You can also create your own artwork for the ammo itself, but for conventional ammunition types, it may be easier just to use the included art.
  
  
  
  
  
  

In my experience, a compatibility patch won’t work perfectly the first time you fire it up. It's just a fact of life. A patch will fail, something won’t behave right, the game may even refuse to load the patch. It happens. Don’t get frustrated, and don’t freak out.

Here are some guidelines for troubleshooting:

• When testing, load only the Rimworld Core, Combat Extended, the concerned mod, and your patch.
  
• Read the log thoroughly. In a lot of cases, it will point you directly to the issue.
  
• Reference other patches, and evaluate whether you’re missing important parts.
  
• When testing an issue, consider not only what isn’t working, but what parts of it aren’t working. In the case of a broken ranged weapon, can a pawn aim with the weapon? Will they fire it? Does a projectile show up? The answer will help you determine what went wrong.
  
• When asking others for help, include relevant error messages, screenshots of the issue, and describe what you did and saw in as much detail as you can.

If you’re dealing with a particularly elusive or frustrating error, consider the following:

• Am I loading all prerequisite mods?
  
• Am I loading the correct versions of my mods and patches, and am I doing so in the correct order?
  
• Is my capitalization correct and consistent everywhere?

Common Issues:

“My patched gun fires, but no projectile appears and I get an error.”
Check that the projectile has the correct Combat Extended-specific Class given to it. Check that you didn’t forget: ‘Class="CombatExtended.ProjectilePropertiesCE’.

While this guide isn't exhaustive by any means, it should put you on solid footing to create a patch. I encourage you to communicate with other patch authors and modders in the Combat Extended discord, and to look through existing patches for items when making your own. Both are infinitely helpful.

The first mod I ever made for Rimworld was a patch for Combat Extended, and I can figure it out, so can you. I hope you find this guide useful, and wish you happy patching!