Resolving Script Conflicts

Resolving Script Conflicts

What a conflict is

Two or more mods shipping their own copy of the same vanilla script — say content\scripts\game\player\r4Player.ws. The game loads exactly one of them, so whichever loses simply doesn't work. Merging combines both mods' changes into a single file that the game loads instead.

Merged output goes into its own mod folder, mod0000_MergedFiles by default. The name starts with mod0000 so it sorts first and wins over the mods it was built from.

---

In Vortex

1. Mods page → Resolve Script Conflicts.
2. A preview runs and shows what would merge, what would be skipped, and any function-level decisions.
3. Confirm, and the real merge runs.

The extension downloads the tool the first time and reuses it after. If a post-deploy scan finds unresolved conflicts, it says so — and the game may not start until they're merged.

---

From the command line

WitcherScriptMerger.Headless.exe merge

That merges every auto-solvable conflict and exits. Options:

Option	Effect
--overwrite	Re-merge conflicts whose merged output already exists. Use after a source mod updates.
--order-file <path.json>	Override the merge order for specific files (below).

Exit codes:

Code	Meaning
0	Every conflict merged
1	Couldn't start — bad arguments, missing config, missing dependency
2	Ran, but skipped one or more conflicts

2 is the one worth checking in a script: it means output exists but is incomplete.

---

In the GUI

Run the executable with no arguments. Conflicts appear in a tree; check the ones you want and merge. Existing merges are listed separately so you can review or remove them.

---

Merge order

Mods merge in a chain: the first two are merged, the result is merged with the third, and so on. Order matters when two mods edit the same lines — later steps merge against the accumulated result.

Default order comes from your game's own load order. To override it for a specific file, pass an order file:

{
  "game\\player\\r4Player.ws": ["modFirst", "modSecond", "modThird"]
}

Rules: list every mod that conflicts on that file, at least two, no duplicates, no unknown names. The merge fails loudly rather than silently merging an incomplete chain.

---

Reading the output

A merge reports each non-mechanical decision:

Merged 42 file(s), skipped 0.
  function-level: game\player\r4Player.ws: function OnSpawned: kept modA's version
    (9 changed diff blocks vs. vanilla, more distinct than modB's 0), discarded modB's
    conflicting change here.

That line means both mods edited OnSpawned, they couldn't be combined, and modA's version was kept because it differed more from vanilla. This is where a "my mod stopped working" answer usually lives. If the wrong side won, override the order for that file and re-merge with --overwrite.

Lines mentioning content "not preserved" are worth attention — they mean a mod's change didn't make it into the output.

---

When a conflict can't be resolved automatically

The file is skipped and a conflict-marker file is written to a DiffPlexConflicts folder, then opened in your default editor. It uses git-style markers:

<<<<<<< modA
        ... modA's version ...
||||||| Vanilla
        ... the original ...
=======
        ... modB's version ...
>>>>>>> modB

Resolve it by hand, save it into the merged mod folder at the right relative path, and the game will use it.

Nothing incorrect is ever written to your mods folder — a merge that can't be trusted writes nothing at all rather than shipping corruption.

---

After a merge

Re-run the merge whenever you add, remove, or update a mod that ships scripts. A merged file built from an older version of a mod is stale, and --overwrite is how you refresh it.

If merging leaves the game unable to start, go to Troubleshooting — several failures look like merge bugs but are caused by the mods themselves or by engine limits.