Installation

Installation

Requirements

• The Witcher 3 (next-gen 4.x is what this is developed and tested against)
• Windows for the GUI; the Headless build also runs on Linux
• Nothing else for script merging — the merge engine is built in

The tool itself

Download from Releases:

Asset	What it is
WitcherScriptMerger-<ver>-win-x64.zip	GUI + CLI + MCP (Windows)
WitcherScriptMerger.Headless-<ver>-win-x64.zip	CLI + MCP only (Windows)
WitcherScriptMerger.Headless-<ver>-linux-x64.tar.gz	CLI + MCP only (Linux)

Extract anywhere. Putting it in the game folder is convenient but not required.

Keep the .config file next to the executable. The archive contains a WitcherScriptMerger.dll.config (or WitcherScriptMerger.Headless.dll.config) holding the paths and settings. Copying the .exe on its own leaves it unable to start.

Pointing it at your game

Three ways, highest priority first:

1. Environment variables — WSM_GameDirectory, WSM_ModsDirectory, and so on. Any setting key can be overridden by prefixing it with WSM_. Useful for scripts and CI, and it writes nothing to disk:

   set WSM_GameDirectory=G:\SteamLibrary\steamapps\common\The Witcher 3
   WitcherScriptMerger.Headless.exe merge
   

2. The .config file — edit GameDirectory (and optionally ModsDirectory, VanillaScriptsDirectory).

3. Leave them blank — paths are then derived relative to the executable's own folder, which is why dropping the tool in the game directory just works.

Check it resolved correctly before merging anything:

WitcherScriptMerger.Headless.exe --version

The Vortex extension

Adds a Resolve Script Conflicts button to Vortex's Mods page, a merge-history dashlet, and a status tile. It downloads and drives the Headless build for you — you do not need to install the tool separately.

Until it's listed in Vortex's in-app extension browser, install it by hand:

1. Grab the extension zip from Releases (tagged companion-<version>), or build it yourself:

   cd vortex-extension
   npm install
   npm run package
   

2. Extract so the files land directly in:

   <Vortex userData>\plugins\witcherscriptmerger-vortex\
   

   That folder must contain index.js and info.json at its top level — not a nested subfolder.

3. Restart Vortex.

<Vortex userData> depends on how Vortex was installed:

Install style	Path
Default, per-user	%APPDATA%\Vortex
Shared / multi-user storage	C:\ProgramData\vortex

If you're not sure, Vortex's own Settings → Mods page shows the paths it's using. Both folders can exist on the same machine — what matters is which one Vortex is actually reading.

Coexisting with Vortex's built-in Witcher 3 support

Vortex ships its own Witcher 3 extension with its own script-merger integration. The two coexist rather than replace each other, but the built-in one can move your merged output around — see The merged mod keeps getting emptied.

The companion extension detects this and tells you when it happens.