THE WITCHER 3
Script Merger by AnotherSymbiote
The Witcher 3 » Utilities
Added: 23/08/2015 - 12:56PM
Updated: 09/07/2016 - 01:52AM

13,683 Endorsements

0.6.2 Latest version

247,520 Unique D/Ls

476,174 Total D/Ls

1,372,553 Total Views

Uploaded by AnotherSymbiote

Description

Last updated at 1:52, 9 Jul 2016 Uploaded at 12:56, 23 Aug 2015

Why It's Useful

When you have multiple mods that modify the same game file, TW3 only loads 1 of the modded versions of that file, overriding all over versions.  This kind of conflict is common & can break mods.  Script Merger tries to make the problem less painful.

What It Does

Despite the name, Script Merger detects mod conflicts in .bundle packages as well as .ws scripts.  Then, it helps you resolve them by creating merged versions of conflicting text files. It leaves the original files untouched, but overrides them. It can't merge non-text conflicts, but for these it can help you manage your custom load order (mods.settings file) to make certain mods override others.

Uses these 3rd-party external tools:
- KDiff3 by Joachim Eibl, for merging text files.
- QuickBMS by Luigi Auriemma, for scanning & unpacking .bundle files.
- wcc_lite by CD Projekt RED, for packing merged text files into .bundle files.

Also contains code from xxHash.NET by Wilhelm Liao, to detect when mod updates have changed files that you merged.

NOTES

When merging, KDiff3 simply does a text merge.  In many cases, that works fine.  But because the tool doesn't actually understand the code, sometimes it can merge things in the wrong order. Auto-resolved conflicts aren't guaranteed to be correct.  In these cases, it needs human help.

Also, script mods can have logic conflicts that the tool can't detect.  In these cases, even if the text can merge without direct conflicts, the resulting script won't work properly.  For example, if Mod A tries to hide the HUD, but then Mod B displays the HUD, Mod A won't work.  Resolving this also requires human help.

NMM users: Currently, Script Merger doesn't support NMM's multi-HD mode (or symlinks in general).





Instructions

1)  Download, extract, & launch Script Merger.

2)  Enter your game's installation path in the textbox at the top.

3)  Click "Refresh" button above the "Conflicts" list.

4)  If mergeable conflicts are detected, repeat these steps until the conflicts are resolved:
     > Choose 2 or more versions of any file(s) to merge.
     > Click "Create Selected Merge" button.
     > If the mods have differences that don't overlap, KDiff3 can merge them automatically.
     > If the mods have differences that overlap, KDiff3 will appear so you can merge them manually.  See below for tutorial videos.
     > If Script Merger can't find the vanilla version of the modded file, you must merge all differences manually when KDiff3 appears.

5)  If non-text conflicts are detected, Script Merger displays them but can't merge them.  So, one of the mods in each conflict will "win" & override the others.  Here's how the winner is decided:
     > By default, the game loads mods in order of folder names — numbers first, then underscores, then letters (not case-sensitive).
     > Or, you can right-click one of the mods to set its priority (1 to 9999, lower number loads first).  Here's an excellent detailed explanation by Kad_Venku.

6)  Play!

7)  When you uninstall or update one of the mods included in a merge, Script Merger will detect the change & prompt you to delete affected merges.  If you update a mod & Script Merger doesn't prompt you delete any of that mod's merges, then they weren't affected by the update.



Tutorial Videos

General Usage
(thanks to Gopher & wghost81)
Note: Gopher's tutorial, though quite helpful overall, says to edit the Script Merger config file manually.  Typically, this is unnecessary & increases the chance of misconfiguration.


Using KDiff3

This video shows a couple KDiff3 basics. This video goes a bit more in-depth.



Example Scenario
QUOTE

Mod 1 - modFOVTweak8070
(link)
  • content\scripts\game\player\r4Player.ws

Mod 2 - modManualCam (link)
  • content\scripts\game\cameras\combat\customCamera.ws
  • content\scripts\game\player\playerInput.ws
  • content\scripts\game\player\r4player.ws

Mod 3 - modNoWitcherSense (link)
  • content\scripts\game\player\r4Player.ws
If we successfully merge all 3 versions of r4Player.ws, then Script Merger will put the merged script here by default:
QUOTE

New Mod - mod0000_MergedFiles
  • content\scripts\game\player\r4Player.ws
The new mod folder starts with "0000_" to ensure that it loads before any other mod folder.  (TW3 loads in ASCII order.)  Because the merged version of r4Player.ws loads first, the non-merged versions will simply be ignored by the game.


Uninstallation

  • To undo all merges & return your mods to their original state, delete the merged mod folder (mod0000_MergedFiles in v0.5, mod__MergedScripts in v0.4.3).
  • To completely remove Script Merger from your computer, delete the files that were in the .zip file you downloaded, as well as the generated MergeInventory.xml file if you have it.