The term spellhook refers to being able to "hook" into the spellcasting process. In other words, it is able to get inside the spell casting process, and based on certain conditions, either allow the process to continue, alter the process to do something other than normal, or stop the process altogether.

How it works[]

In order to get spellhooking to work, the following steps must be taken.

  1. The name of the spellhook script must be set on the module as a local variable. This can be done in one of two ways.
    1. Setting the name of the script in the toolset when building the module.
      1. Go to the "edit" menu, and choose Module properties
      2. Under the advanced tab, there'll be a button named "Variables"; click it
      3. You'll see a window with existing variables on the module (will be empty unless you've set some previously)
      4. In the "Name" part, write: X2_S_UD_SPELLSCRIPT
      5. In the Type part, select String
      6. In the Value part, enter the name of the script you want to execute when a PC casts a spell, without the .nss extension.
      7. Click the Add button.
    2. Setting the name of the script programatically during the game via script, replacing scriptname with the name of the script to execute. This value can also be deleted to "turn off" the spellhooking process.
      SetLocalString(GetModule(),"X2_S_UD_SPELLSCRIPT", "scriptname");
  2. The actual script for the spellhook needs to be written. This script will check for the special circumstances that will affect spellcasting, and depending on the results, either continue the original spell script without doing anything, stop the original script, or perform some additional actions and then either continue or stop the original script.

Stopping a spell script[]

In order to stop a spell script, two things must be done. First, the file x2_inc_switches must be included by the spellhook script. This should be done at the top of the script, outside the main() function.

#include "x2_inc_switches"

Second, the function SetModuleOverrideSpellScriptFinished() must be called to cause the original spell script to stop.


In short, this function sets a value that causes the original script to end. This is done through the following code that is included in all spell scripts at the beginning of the main() function.

// Spellcast Hook Code
// Added 2003-06-20 by Georg
// If you want to make changes to all spells, check x2_inc_spellhook.nss to
// find out more
if (!X2PreSpellCastCode())
// End of Spell Cast Hook

New, custom spells that are added to the game should also include this snippet of code at the beginning of their main() function in order to be able to utilize the spellhook system.


  • Spellhooking only works for PCs, unless the variable X2_L_WILD_MAGIC is set to 1 on each area where NPCs are to use the spellhook system. To circumvent this and allow NPCs to always use the spellhook script, the function X2PreSpellCastCode must be edited. This function is found in the file x2_inc_spellhook.

External Links[]