-
Notifications
You must be signed in to change notification settings - Fork 0
Known Limitations
Stated plainly, so you can decide whether this tool covers your case before you rely on it.
Script (.ws) and XML conflicts merge with no external dependencies. Conflicts inside
.bundle packages additionally need:
-
QuickBMS + its
witcher3.bmsplugin — to unpack - wcc_lite (from CD PROJEKT RED's REDkit/ModKit) — to repack
Neither is committed to this repository. Both are third-party binaries with unclear redistribution terms, and that decision is deliberate — it matches the original upstream project's precedent.
Practical impact: the overwhelming majority of real conflicts are flat .ws files, and
those work out of the box. If you hit a bundle-content conflict without the tools
configured, the scan says so and skips it rather than failing the run.
The bundle path has also never been round-tripped end to end against a real bundle-vs-bundle conflict in either host. Treat it as unverified.
The game itself stops building its main menu past roughly 256 .bundle files under
Mods\. Nothing this tool does can raise that. See
the main-menu symptom
for how to count and what to do.
Worth knowing because it looks exactly like a merge failure and isn't.
A mod shipping a whole-file copy of a vanilla script taken from an older build doesn't contain declarations vanilla added since. A three-way merge cannot tell that apart from a deliberate deletion.
See A mod is built for an older game version. This is a property of three-way merging, not a bug that can simply be fixed — the two cases are genuinely indistinguishable from the file contents alone.
Vortex ships its own script-merger integration that backs up and restores the merged mod folder per profile, and swaps it during Collection installs. It can empty or replace merged output that this tool produced.
The companion extension detects the change and warns, but cannot prevent it. See The merged mod keeps getting emptied.
The per-file audit trail — every tiebreak, every discarded edit — is printed by the CLI and shown in the Vortex dialog, then gone. If the game misbehaves a week later there's no stored record of which mod won which function.
Capture the merge output if you expect to need it.
Removing existing merges is only available in the GUI. The CLI and MCP surfaces can create merges but not delete them, so Vortex users — who get the GUI-less Headless build — have no supported way to undo one beyond deleting the merged mod folder by hand.
The GUI is Windows-only (WinForms). The Headless build runs on Linux, but the game and Vortex don't, so Linux support is mostly useful for CI and automation.
The underlying three-way diff library has a known upstream defect that can, at low rates, produce internally inconsistent diff blocks. This tool defends against it: every "clean" merge output is validated against content invariants before being trusted, and a violation falls back to the function-level engine rather than shipping the result.
The failure mode is therefore fail-safe — a suspect merge writes nothing rather than writing something subtly wrong. If a file is unexpectedly skipped with an invariant message, that's this defense working.
WitcherScriptMerger