The Tome of
Witcher 3 Modding
Table of Contents
1. Introduction
1.1 Introduction
1.2 Regarding This Document
2. The Witcher 3 Game Directory
3. Installing Mods
3.1 Prep Work
3.2 Installing Mods
3.3 Setting Priorities
3.4 Using Mod Managers
4. Mod Conflicts
4.1 Merging Scripts
4.2 Merging Bundled Text
5. Launching the Game
1. Introduction
1.1 Introduction
This document serves as a properly established guide for newcomers
to the modding scene of The Witcher 3. The document aims to
establish what to do when installing, uninstalling and updating mods
as well as how to deal with inevitable mod conflicts, as well as other
things
1.2 Regarding this document
The document is subject to change depending on feedback and can be
considered not fully completed. Keep this in mind when browsing
Any feedback and comments on this document should be directed to
myself (Username: Ferroxius) in either:
The Witcher 3 Modding Community (https://discord.gg/VBH8qEHT)
Wolven Workshop (https://discord.gg/zM6UQc8k)
It is recommended that you read the entirety of this document so as
to not potentially miss some important information
This document will only explain modding in terms of the current
version of The Witcher 3 (As of right now, v4.00). This means that if
you are planning on modding on the pre-update version of The
Witcher 3 (v1.32) then some information may be different
2. Witcher 3 Game Directory
The two images shown above are examples of the main W3 game
directory (Steam and GOG). This will be where you install and
uninstall mods
Pay attention in particular to these folders:
bin - Contains xml files for the games menus as well as other
configuration files
content - Contains the games vanilla scripts and bundles
dlc - Contains the bundles for all 20 free dlcs as well as the two
expansion packs
mods - Contains any mods you install. This folder by default doesn’t
exist so make sure to create one
3. Installing Mods
3.1 Prep Work
Before installing mods for The Witcher 3 ensure the following:
- You have a fresh installation of The Witcher 3 with no extra or
leftover files
- You have a tool like 7zip or WinRAR that can extract files from
archives
- You have installed and setup Script Merger which you will
require for dealing with mod script conflicts
3.2 Installing Mods
When you download and extract a mod it may contain one or more of
the following:
- A mod file e.g. modRandomName
- A dlc file e.g. dlcRandomName
- A bin folder containing an xml file e.g. randomname.xml
- An input.settings file or some other file containing custom
keybinds
3.2.1 Installing mod files
Place the mod file in your mods folder
3.2.2 Installing dlc files
Place the dlc file in your dlc folder
3.2.3 Installing xml files
Most xml files come with the path figured out in a bin folder. As such
you can simply place the bin folder in your main directory and it will
automatically be placed in the right location
If this is not the case then the xml file should be placed at:
bin\config\r4game\user_config_matrix\pc
Additionally, custom xml files need to be added to the games filelist.
Open up either dx11filelist.txt or dx12filelist.txt depending on
which API you use and add the name of the custom xml to the bottom
of the list
Make sure to add the semicolon (;) to the end of the line just like the
other xmls
3.2.4 Adding custom keybinds
Navigate to Documents\The Witcher 3 and find a file called
input.settings and open it
The keybinds file included with the mod will contain keybinds that
look like this:
[Exploration]
IK_NumPad5=(Action=UpdateRandomName)
Find the relevant section of the main input.settings file and
copy-paste the new keybinds below it
3.3 Setting Priorities
When two mods edit the same file they will be in conflict with one
another. These conflicts can be resolved but some require advanced
modding knowledge. As such it is more straightforward to set
priorities, this will mean that the changes of one mod will have
priority over another and have its changes be present in the game
3.3.1 Setting Priorities with mods.settings
Navigate to Documents\The Witcher 3 and find a file called
mods.settings. This might not exist by default so if you don’t see it
then create a text file and name it as such
Once found, open it. Setting a priority is as follows:
[modRandomName] ←The mod name. Include the square brackets
Enabled=1 ←Enabling the mod to appear in game
Priority=10 ←The priority number e.g. 10
When setting the priority number keep in mind that the lower the
number, the higher the priority meaning for example: 5 is higher
priority than 10
3.3.2 Setting Priorities with a Mod Manager
(To be added)
3.3.3 Setting Priorities alphanumerically
The name of a mod can be used to set priorities as well. The Witcher 3
by default reads the priorities of mods in alphanumerical order
meaning that for example: b is higher priority than g. Numbers and
underscores can also be used as priorities higher than a
3.4 Using Mod Managers
A Mod Manager for the unaware is a tool that is capable of installing,
uninstalling and managing mods without the need to do this yourself.
It is convenient and a good solution for those seeking an easier
modding experience
However, do keep in mind that The Witcher 3s Mod Managers are not
100% reliable and can incorrectly install mods which can result in
them not working correctly in game. Be considerate of this when
troubleshooting
You should only use two Mod Managers specifically for The Witcher 3:
- The Witcher 3 Mod Manager
- Vortex
Pros of using a Mod Manager Cons of using a Mod Manager
Is typically highly reliable with its purpose Has the possibility to incorrectly install mods
More straightforward and easy to use
4. Mod Conflicts
When two mods edit the same file they will be in conflict with one
another. A reliable method of checking for conflicts is through Script
Merger which will highlight the conflicting file and what two or more
mods are editing it. Script Merger will also tell you the current state of
the conflict which can be:
Red - Unresolved conflict
Purple - Resolved conflict through set priorities. The mod winning the
priority will be highlighted
Blue - Resolved conflict through merging
In Script Merger there are three types of conflicts:
- Script conflicts
- Bundled Text (xmls) conflicts
- Non-Bundled Text (not xmls) conflicts
Only script and bundled text conflicts can be resolved through
merging. Non-bundled text can only be resolved through priorities
4.1 Merging Scripts
Click the checkmarks for the mod scripts you wish to merge and then
select at the bottom “Create Selected Merge”. Script Merger will then
attempt to merge the scripts. If the merge occurs without any issues it
will tell you, if the merge requires intervention then kfiff (One of
Script Merger’s tools) will open
4.1.1 Resolving non-automatic script merges
Resolving non-automatic script merges comes down to picking the
right line of code from one mod or another.
You are offered three script versions, the vanilla scripts, mod Bs
scripts and mod Cs scripts. It is up to you to pick either A if you want
vanilla, B or C. Picking one doesn't stop you from picking another.
You can pick both A & B, or B & C etc... Remember that you should
rarely pick A as it is vanilla, and you're merging mods for a reason
because you don't want vanilla.
For each conflict, you should use the A, B, C buttons to pick the
version of the code you want. Then you use the arrow buttons to move
from one conflict to another. In the image you can see both B and C
were picked. And there is no other conflict in the current file.
Once done, ctrl-s and close the window
4.2 Merging Bundled Text
(To be added)
5. Launching the Game
On launching the game you may notice this popup appearing
This is The Witcher 3s script compiler. It is checking through the
scripts of your mods to make sure that everything is in order before
launching. If it detects an error it will display a message explaining
what is wrong. It will look something like this:
If you receive a message like this then you need to figure out what is
wrong. Sometimes it can be the result of bad script merging,
sometimes it could be an issue with the mod itself
