Made with the Witcher III Modding Tool, developed and released by CD PROJEKT RED for use with The Witcher III: Wild Hunt. © 2014 and © CD PROJEKT RED. All rights reserved. Check out the Witcher III Modding Tool here: [http://redkit.cdprojektred.com/]
Quest events for The Witcher 3 Remastered, in WitcherScript. Find out when a quest block starts, finishes and moves on, without changing a single quest file.
Mods that follow quest progress have always had to edit .w2phase files to add script or fact blocks. Those edits are what makes quest mods conflict with each other. Native Quest Hook does away with that. Your mod names the blocks it cares about by their GUID, and it hears about them as the game runs them.
public function OnBlockFinished(guid : string, output : name)
{
// "Interaction dialog" in At the Mercy of Strangers finished, and the player chose Help
}
The game's engine still has the quest listener REDkit's quest debugger uses. Every quest thread calls it whenever a block activates or deactivates. Nothing listens in a normal game.
- It listens:
NativeQuestHook.asiattaches a listener of its own. There's no detour on quest code: it runs off the quest system's own tick. - Cheap in the engine: the engine's callbacks only copy what happened. Everything else waits until the quest tick has finished.
- Filtered: only the blocks mods have asked for are passed on to script, through a plain typed call. About 10,000 block events can fire around a single load, so that matters.
- Moved on, with the output: when a block finishes, the hook reads the output it fired, and where that output leads, from the block's own links.
- Loads and world changes: it tells real progress apart from blocks the game is only restoring after a load, a fast travel or a world change.
Download Native Quest Hook from its Nexus page: https://www.nexusmods.com/witcher3/mods/15527
- Install Ultimate ASI Loader (ThirteenAG's loader, packaged for the game by voidom1): it adds
winmm.dlltobin\x64_dx12. Install only one ASI loader. - Copy
NativeQuestHook.asiintobin\x64_dx12. - Copy
modNativeQuestHookintomods.
It needs no settings. Its log is bin\x64_dx12\NativeQuestHook.log.
Your mod needs no .asi or C++ of its own: only modNativeQuestHook installed beside it. If a player doesn't have NativeQuestHook.asi, your mod still compiles and runs, and its listener simply hears nothing.
1. Find the GUIDs. Every quest block has a GUID that stays the same across patches and mods:
- Brothers In Arms keeps 130,541 of the vanilla game's 130,545.
- Progress on the Path keeps every one of Brothers In Arms'.
Decode the phase with W3 Mod Workbench (--to-json) and look for the block's guid. Or set LogEveryBlock=1 (see Debugging) and play the quest.
watched takes a GUID in any of the forms you'll find it in, in upper or lower case:
- the standard form, as W3 Mod Workbench and the log show it:
4b435b43-30c2-40d8-9eae-08df8d1b7df9; - REDkit's, as its property grid shows it:
4B435B43-40D830C2-DF08AE9E-F97D1B8D; - either in braces, or the standard form's 32 digits without dashes.
They all name the same block. Your callbacks get the GUID back exactly as you wrote it in watched, and NQH_NormaliseGuid(guid) turns any of them into the standard form.
2. Write a listener.
class CMyMod_Listener extends CNQH_Listener
{
public function Init() : CMyMod_Listener
{
watched.PushBack("4b435b43-30c2-40d8-9eae-08df8d1b7df9"); // Interaction dialog: Help or Nope
watched.PushBack("4f6a4f44-3e1a-40f4-bd24-ebb2b16f1232"); // Pause: the player left the area
return this;
}
public function OnBlockFinished(guid : string, output : name)
{
if (guid == "4b435b43-30c2-40d8-9eae-08df8d1b7df9" && output == 'Help')
{
// the player helped him
}
}
}
3. Register it.
@wrapMethod
function NQH_RegisterListeners()
{
wrappedMethod();
NQH_Register('MyMod', (new CMyMod_Listener in theGame).Init());
}
NQH_RegisterListeners is called once a session. You can also call NQH_Register yourself at any time; registering again under the same id replaces your listener.
A complete example is in examples/modNQHExample.
| Event | When |
|---|---|
OnBlockActivated(guid) |
A watched block started |
OnBlockFinished(guid, output) |
It finished and fired output, which is what moves a quest on. None for blocks whose output has no name, such as pause blocks. |
OnBlockActive(guid) |
It was already running when you registered, or the game restored it after a load or a world change |
OnBlockStopped(guid) |
It stopped without finishing: a load, leaving its world, or the quest moving past it |
| Function | |
|---|---|
NQH_Register(id, listener) |
Registers a listener, or replaces the one with that id |
NQH_Changed() |
Call after changing a registered listener's watched |
NQH_IsBlockActive(guid) |
Whether a watched block is running now |
NQH_NormaliseGuid(guid) |
A GUID in any accepted form, as the standard lower-case form |
NQH_IsNativeActive() |
Whether NativeQuestHook.asi is installed and working |
NQH_ApiVersion() |
The script API's version, 1 for now |
OnBlockFinishedcomes one tick before the next blocks run. That makes it early enough to stand in for a script block you'd otherwise add to a quest.- One output can lead to several blocks, and blocks can join and loop. Watch the block whose finishing you care about, not the one after it.
- A GUID is unique across the game and its DLC. One shared external phase can still run in several places at once, though. Mods can also copy blocks and create duplicates.
To log every quest block the game runs, not only watched ones, create bin\x64_dx12\NativeQuestHook.ini with:
[Debug]
LogEveryBlock=1Each line shows:
- the block's class, name and GUID;
- the phase it's in;
- the output it fired;
- the GUIDs of the blocks that output leads to.
The log can be read while the game is running.
It knows the current Steam build of The Witcher 3 (exe timestamp 0x6ADFBD7A), and checks the code at every address it uses.
On any other build it searches the exe for everything it needs. If any of it can't be found exactly, it switches itself off and logs why. It never guesses. Your listeners then hear nothing, and NQH_IsNativeActive returns false.
- The .asi: CMake and Visual Studio 2022 (x64). Set
W3_GAME_DIRto install into your game folder after each build. - The scripts:
sh tools/compile.shcompiles them with REDkit'swcc_liteintoprecompiled.rsblob. - A release:
sh tools/create-release.sh [version]builds both from the last commit and makes the installable zip inbuild/release. The version defaults to the commit's tag.
The research behind it, from which functions to call to the layouts of quest blocks and threads, is summed up in the source's comments.
The code is MIT, © 2026 Faen90. It's free to use, change and build on.
The Witcher 3 and REDkit are CD PROJEKT RED's. This is an unofficial mod, and isn't endorsed by them.