Spellhook

Definition
The term spellhook refers to being able to "hook" into the spellcasting process, or, in other words, it means to be 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.
 * 2) Setting the name of the script in the toolset when building the module.
 * 3) Go to the "edit" menu, and choose Module properties
 * 4) Under the advanced tab, there'll be a button named "Variables"; click it
 * 5) You'll see a window with existing variables on the module (will be empty unless you've set some previously)
 * 6) In the "Name" part, write: X2_S_UD_SPELLSCRIPT
 * 7) In the Type part, select String
 * 8) In the Value part, enter the name of the script you want to execute when a PC casts a spell, without the .nss extension.
 * 9) Click the Add button.
 * 10) 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");  DeleteLocalString(GetModule,"X2_S_UD_SPELLSCRIPT");
 * 11) 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. Second, the function SetModuleOverrideSpellScriptFinished must be called to cause the original spell script to stop. SetModuleOverrideSpellScriptFinished; 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) {   return; } // End of Spell Cast Hook New, custom spells that are added to the game should also include this snippet of code in order to be able to utilize the spellhook system.
 * 1) include "x2_inc_switches"