-
Notifications
You must be signed in to change notification settings - Fork 304
Compatibility Patch Guide
This guide serves as an introduction to xml compatibility patches for Combat Extended and provides a walkthrough for creating patches for several different types of content commonly found in mods—patches that require C# work are outside the scope of this guide and are generally handled on an individual basis.
The entire process of creating an xml patch is relatively straightforward. In most cases, much of what you need already exists elsewhere in another patch, and you can copy-paste to save yourself a lot of effort formatting files and xpath operations. So, the next time you see an unsupported mod, instead of asking “ce patch when?”, consider taking a crack at making a patch yourself!
Combat Extended completely and dramatically overhauls Rimworld’s combat mechanics, replacing a largely percentage and random number-driven system with a physics-based model. We overhaul everything from projectile flight modeling and interception to the basic functionality of the armor system and, in brief, this requires a lot of custom code and a lot of changes.
While the team has created a few built-in autopatchers to (roughly) handle some common items, handling such a wide array of changes isn’t easy to automate. To that end, compatibility patches serve two chief functions; firstly, to allow basic functionality of the mod’s contents with Combat Extended and, secondly, to balance vanilla values.
The compatibility requirements of every mod should be evaluated on an individual basis, and there are a few hard and fast rules regarding what does and doesn’t require a compatibility patch. Moreover, there are different degrees of functionality for unpatched mods—some may not work at all without a patch, while others may work fine but still get patched for balance considerations.
If in doubt, remember this; if it attacks or gets attacked, it likely needs a patch. Beyond that, playtesting the mod content will generally show you what does and doesn’t work.
The following is a non-exhaustive list of mod content that usually requires a compatibility patch to be fully functional and balanced with Combat Extended:
- Weapons, ranged or melee.
- Pawns (animals, humanoids, mechanoids, etc.)
- Custom pawnKinds, such as those from faction mods.
- Turrets, manned and automated.
- Vehicles with weaponry or meaningful amounts of armor.
- Custom artillery/mortar shells.
- Apparel, especially armor
- Implants, body parts, xenotypes, etc. that add new attack abilities.
- Materials that can be used to make armor or weapons.
Other types of mod usually do not require patching for Combat Extended, such as:
- Custom biomes that don’t add new animals or weapon/armor crafting materials.
- Custom xenotypes and genes that don’t have armor values or new attacks.
- Purely cosmetic mods (lighting, hair styles, retextures, etc.)
- Furniture and workbenches.
- Custom ideologies.
- Custom map generation mods.
- Interface and Quality-of-Life Mods.
Additionally, some content deserves special mention:
- Apparel that doesn’t provide much protection—like basic clothing—is patched for balance, but the difference in armor values if often quite small, and it may work as-is.
- pawnKinds that use already supported weapons will be functional, but they may not spawn with appropriate amounts of ammo for the weapon and purpose.
- Scenarios that start with patched ranged weapons are patched to provide the player with an appropriate amount of ammo to start with, but don’t strictly require a patch.
- Similarly, traders are patched to let them stock CE ammo and crafting resources.
- For some workbenches, it may be sensible to patch in recipes from Combat Extended but, again, this isn’t strictly required for them to work.
- Psycasts need to be evaluated on a case-by-case basis, as some combat-related ones may need patched to work.
Finally, while the Combat Extended team puts in a lot of work to provide support for as many different types of mods as possible, there are a few out there that are simply incompatible with Combat Extended.
Fortunately, there are relatively few hard compatibilities, and they mostly consist of mods that either add features already within Combat Extended—like stabilization or an ammo system—or touch vanilla features that Combat Extended does away with, like changing the accuracy of vanilla mortars. The Combat Extended About.xml file contains a list in the <incompatibleWith> section, but this isn’t exhaustive.
For brevity’s sake, this guide will assume you have a basic familiarity with xml and the xpath patching system. If you’re brand new to the subject, then I would strongly recommend looking over the Rimworld wiki. It can offer useful resources for learning both xml and xpath, and for the particulars of Rimworld mod folder formatting and the like.
To get started, what you’ll need is:
- A copy of Rimworld, legally owned and of the latest stable build.
- A local copy of the latest release of Combat Extended and its dependencies.
- A copy of the mod you want to patch, along with any dependencies.
- A text editor of your choice, such as Notepad++ or Visual Studio Code.
For ease of editing, you’ll want a local copy of Combat Extended. If you haven’t used your local mods folder already, check out the wiki for an overview.
Before setting out to write a patch for a mod, it’s important that you confirm that the mod needs a patch and that one doesn’t already exist elsewhere.
For the first part, refer to the What Needs Patched? section of this guide. For the second part, you’ll have to review the mod in question and the Combat Extended patches. You can find a complete list of compatibility patches integrated into Combat Extended here.
Note, this list does not include any mods patched externally—such as those with a standalone patch or a patch integrated into a third-party mod. To find those, you’ll have to do some looking around; check the mod files, search the Steam Workshop, etc.
The following are some general rules on patch making:
You should—within reason — do what you can to minimize the size of your patch without sacrificing functionality or readability. That may mean consolidating small files together, combining patch operations (such as folding a PatchOperationAdd into a PatchOperationReplace that touches the same xml elements), and avoiding unnecessary patching.
It’s a lot faster to copy-paste and modify that to make from scratch. Writing a patch? Look around for an outdated one you might be able to fix up in less time. Patching a modern firearm? Look through the patch files to see if it’s already been patched for another mod and work from that.
Obviously, Combat Extended radically upends the balance of Rimworld combat—weapon ranges are greater, weapons are more lethal and fill more niche roles, and numerous other changes all make it a far different game. Even so, when patching mod content, we aim to preserve the relative vanilla balance of items against each other wherever possible.
In addition to this guide, there are many other useful resources and references that can help you make your compatibility patch. Keeping them handy can be the difference between quick and straightforward success and drawn-out frustration and confusion.
The single most useful resource will be the hundreds of integrated patches already contained within Combat Extended. Most types of Rimworld mod content have already been patched by someone, and you are strongly encouraged to reference them and copy-paste from existing patches wherever possible. Not only is it a massive time-saver, but it can also be useful for keeping balance consistent across the various mods.
Another set of useful resources are the spreadsheets used to calculate the stats of various weapons and projectiles. While these are generally best suited for conventional weapons and projectiles, they can still be a useful resource for more exotic content. Remember, these sheets are guidelines and tools, and they’re only as good as the numbers you enter.
If you’re still left with questions, the next place to turn is the Combat Extended discord server. The community includes a sizable group of contributors and mod authors with experience making and troubleshooting patches.
Below are a series of overviews for different types of patches in order of complexity, starting from least complex to most.