Dependencies and ordering

The patch lifecycle covers the coarse timeline: passes and buckets. This page covers the finer controls that let your patch coordinate with specific mods and specific patches: requiring them, refusing them, and ordering around them.

Patch ids and namespacing

Every patch has a full id of the form modId:patchName. When you write PM.Parts:Patch("KerbalImpactToleranceFix") in a mod whose id is BetterFixes, the patch's full id is BetterFixes:KerbalImpactToleranceFix. The namespace is added for you, which is why two mods can both have a patch named Fixes without colliding.

When you refer to a patch in the methods below, you can use the short name for your own patches (it gets your mod id prepended automatically) or the full modId:name for another mod's patch.

Requiring and refusing mods

These take mod ids and decide whether your patch runs at all:

  • :Needs(modId, ...) runs your patch only if all of the listed mods are on. Use it when your patch edits content that a different mod adds. If that mod is not on, the summary then shows a useful message.

  • :Conflicts(modId, ...) skips your patch if one of the listed mods is on. Use it when your change and the change of a different mod must not both apply.

A mod is on when it is installed and its default feature is on in the feature set that PatchManager builds. A campaign can have an installed mod turned off. Then the content of that mod does not load, its patches do not run, and :Needs and :Conflicts do not count it. During registration, no feature set is active, so each installed mod counts as on.

PM.Parts:Patch("RetuneModdedEngine")
        :Needs("EnginePack")
        :Named("their_engine_id")
        :Do(function(part) ... end)

If the requirement is not met, the patch is removed and the reason appears in the summary.

Requiring and refusing patches

These take patch ids and work at the individual-patch level:

  • :NeedsPatch(patchId, ...) runs your patch only if every listed patch also runs.

  • :ConflictsPatch(patchId, ...) skips your patch if any listed patch runs.

Use these when your change depends on or duplicates a specific other patch rather than a whole mod.

Ordering: before and after

These do not decide whether your patch runs, only when, relative to others in the same bucket:

  • :AfterPatch(patchId, ...) runs your patch after the listed patches.

  • :BeforePatch(patchId, ...) runs your patch before them.

  • :After(modId, ...) runs your patch after every patch from the listed mods.

  • :Before(modId, ...) runs your patch before every patch from the listed mods.

PM.Parts:Patch("FinalTouchup")
        :AfterPatch("EnginePack:RetuneEngine")
        :Do(function(part) ... end)

The critical limitation, repeated from the lifecycle page: before and after only apply within the same bucket of the same pass. If your patch and the target are in different buckets, the relationship is silently ignored, because the buckets already order relative to each other. To order two patches against each other, put them in the same bucket (for example both in Default, or both made :First()), then use before and after.

Take careful heed to not cause a cycle here, the patch summary will tell you if a cycle occurs but these tools make it exceedingly easy to do so if you order stuff the wrong way. For example if a mod has a set of patches that wants to run after all the patches of your mod but then you make a patch that runs after a patch in it, that will cause a dependency cycle. A decent way to avoid this is to only use :Before and :After sparingly and generally rely on :BeforePatch and :AfterPatch.

The whole-pass shortcuts

:First(), :Last(), :Early(), and :Late() from the lifecycle page are the coarse version of this. They are blunt: they move you relative to every other patch at once. Most patches should set none of them and stay in Default, where before/after can order them precisely against the specific patches that matter. Use the passes and buckets only when you need to be near the front or the back of the whole run, which is uncommon for most normal patches.

A practical recipe

  • Patch edits another mod's content: :Needs that mod.

  • Patch must not coexist with another mod's change: :Conflicts that mod.

  • Two of your own patches must run in a set order: same bucket (Default is fine), then :AfterPatch between them.

  • You truly must run before or after a particular other patch: :BeforePatch / :AfterPatch, making sure you share its bucket.

Note the recipe does not use :Early():First(). Redux's own patches use it because the base overhaul wants to be the absolute baseline (see the patch lifecycle). A normal patch is better off in Default, ordered with before/after only where it needs to be.

For the bigger picture of writing patches that play well with an ecosystem of other mods, see Cross-mod compatibility.