Welcome to Script Merger: Fresh & Automated Edition!

Is this your first time using Script Merger? Scroll all the way to the bottom, to the Welcome to New Script Merger Users section, or the rest will not make much sense. Not a new user (or feeling risky)? Keep reading!

TL;DR

Script Merger - Fresh & Automated Edition (SM-FAE) (no pun intended) is a new Script Merger application, based on the the original Script Merger that we all know and use. The improvements mainly lie in two areas: 1. A completely redesigned and Fresh UI, with support for Windows Light & Dark mode. 2. Several new Automation and usability features, which you can turn on/off in the Options, to allow for completely automated merging experience in many situations. So what does it look like?



Want to see a quick 90-second demo? (Note this is of beta 0.9.1, a new video will be made for 1.0.0!)




What's Fresh?

Well, the most obvious thing is a completely redesigned user interface, with support for Windows Light & Dark Mode. By default the application will match your current Windows theme, but you can also set your preferred theme via the Options. UI clutter has been removed and the UI is more responsive. It reacts to user interaction/mouse movement, and will support almost all desktop resolutions and scaling sizes (at least up to 250%, and mostly even higher). Besides that, there have been several smaller improvements, designed to make the application more user friendly, especially for users new to Witcher 3 modding. The default options have been tweaked. New keyboard shortcuts have been added, as well as a screen explaining the shortcuts available. A button has been added to restore default settings. Buttons have been added to Create All Script Merges and Delete All Merges in a single click. And I'm not mentioning everything here.

What's Automated?

The Options screen has been updated with 5 new Automation options (detailed explanation further down):

Besides that, there are several smaller improvements, some under the hood and some visible. For example: When starting SM-FAE for the first time, it will automatically find your GOG/Steam Witcher 3 game directory. It will automatically fix a missing Mods directory. It will warn you when there are merges existing, but there is no record of them in the Script Merger history, and with your confirmation will fix it for you.

Automation Caveat

There is one thing that can't be automated though, and that's when a hard conflict occurs. A hard conflict is when two mods, change the same line(s) in the same file, which can't be auto-merged without a human decision. In that case the Merge tool (KDiff3) will popup. KDiff3 has been slightly reconfigured to make it somewhat easier (for example white space changes are now ignored by default), but still, this can be a difficult process. The only real way to improve this, is if mod makers change less lines of code in the original scripts. It's completely possible to make huge changes to the game, by properly organizing code in separate files. Many mods already do, but even more sadly don't. If you encounter hard merge conflicts, talk to the mod author(s), ask them to make them more merge friendly. SM-FAE can't do anything about it!

Credits

As I said in the intro SM-FAE is based on the original Script Merger, which was made by AnotherSymbiote. Many, many thanks for all the hard work! And after that Partoutatix and woodbyte created the "Unofficial Patch" which was later integrated into SM. Also thanks to them.

I also want to give a general shoutout here to Aeltoth and ElementaryLewis, for helping tons of users and mod developers like myself on the WolvenKit Discord!

Basically from the start of Script Merger in 2017, the Script Merger source code has been made available publicly available under the GPLv2 license. Allowing anyone who complies with the license to reuse and change the open source code. Github summarizes the license like so:

SM-FAE will of course continue like that. The source code of this new version will be available on my Github repo starting from version 1.0.0 at the latest, and every update after that. (I'm currently still cleaning up many rough spots in the code and want to publish a reasonably clean version.)

3rd party tool credits

SM-FAE uses these 3rd-party external tools:

• KDiff3 by Joachim Eibl, for merging text files.
• QuickBMS and the Witcher 3 BMS plugin by Luigi Auriemma, for scanning & unpacking .bundle files.
• wcc_lite by CD Projekt RED, for packing merged text files into .bundle files.
• Code from xxHash.NET by Wilhelm Liao, to detect when mod updates have changed files that you merged.
  

Downloading

There are two version you can download:

• SM-FAE Standalone
• SM-FAE Full
  

SM-FAE uses some external tools to do it's job (listed above). If you already have them, or want to download those separately, you can pick the Standalone version. If you want the full package with everything included, pick the Full version.

Installation

If you use Vortex
Vortex installs the regular Script Merger automatically in the [Witcher 3]\WitcherScriptMerger directory. If you want to upgrade, I recommend renaming that directory, to WitcherScriptMerger.old. Then create a new [Witcher 3]\WitcherScriptMerger directory, and extract the .7z there. From now on Vortex will use SM-FAE, and of course you can also start it manually.

If you use Witcher 3 Mod Manager (W3MM)
W3MM does not include Script Merger out of the box, so first follow the manual installation steps below. Then start W3MM, click Settings in the menu at the top (NOT the big Settings button with the book icon), go to Configure Settings, Change Script Merger Path, browse to the directory where you extracted SM-FAE, and select WitcherScriptMerger.exe. From now on W3MM will use SM-FAE.

Manual (You don't use a mod manager)
Extract the .7z file to a clean directory of your choice and Start WitcherScriptMerger.exe to get the ball rolling!

How to fallback to regular Script Merger
If you run into any issues, you can easily fallback to the regular Script Merger version. If you do that though, you should remove the [Witcher 3]\Mods\mod0000_MergedFiles directory, before starting regular Script Merger, or SM will treat the merges made there by SM-FAE as if it were a mod by itself. Nothing terrible will happen, but most likely merging will fail or the game won't launch and you still have to delete this directory anyways, so SM can recreate the merges.

Note: SM-FAE is built on .net 6.0. Depending on your Windows version and other installed apps, you may need to install a Runtime Library for that. First just try to start the app, if nothing happens or a message appears relating to this, then most likely the following Microsoft downloads will resolve this:

X64: https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-6.0.20-windows-x64-installer
X86: https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-6.0.20-windows-x86-installer

Explanation of new Automation Options

• Automatically create all script merges
  This automatically starts merging all scripts immediately when starting SMFAE. This follows the same process as when you click the Create All Script Merges button.
• Automatically delete out of date merges
  When a mod is removed, or updated, this option will automatically delete the previous merge(s), so updated merge(s) can be created afterwards (if required).
• Automatically overwrite old merges
  When a mod is added and changes a script file for which a Merge already exists, this option will automatically overwrite the old Merge, with a new Merge  where the new mod is combined into as well.
• Automatically skip KDiff3 info dialogs
  Normally the merge tool (KDiff3) shows an information dialog after every merge, saying how much lines were changed and some other basic details. With many mods, that's a lot of OK clicking, so this option makes it so you don't see those dialogs anymore.
• Automatically exit when all merges complete
  If you turn on this option, when merging is complete, a screen will show, telling you so. There are two buttons here: one to cancel automatic exit (or press Esc), and one to exit immediately (or press Enter). If you don't do anything, after 2 seconds SM-FAE will exit automatically. This option does not take "bundle" merges into account. Often it's better to handle those with mod priorities in my experience, they also get changed less often and are slow to scan (has to process up to 20GB of data).

Welcome to New Script Merger Users

Last, but certainly not least! And only last because this is currently in beta release candidate 1.

Script Merger is a tool that detects conflicts between mods & helps you resolve them, either by creating merged files that override the conflicting ones, or by configuring a custom load order for your mods. Merges are easy to undo because they don't change the original mod or game files. Depending on your mods, some merges may require basic understanding of code.

The page you're looking at now is about Script Merger: Fresh & Automated Edition. This is a new version of Script Merger with several improvements. This is however currently in beta release candidate 1. So, unless you want to jump straight into the deep end, I recommend you start by using the original Script Merger for a while.

Click here for info and download!

Do keep an eye on this page though. Hopefully the beta phase won't take too long, and then I'll replace this notice with proper instructions for new users (which perhaps you don't need anymore by then ;).