Tag based scripting:

Although there are several tutorials out there on this subject already, I felt a need to write one that explains Tag Based Scripting using the default script method laid out by Bioware and Obsidian. All the tutorials that I have looked over on this subject change or alter the default module level scripts to the authors “ideal” way to do Tag based Scripting. This is all fine, and all the methods work, however I feel that it further confuses the Newbe not only when setting their own system up, but also when asking questions on the forums. When a Newbe asks for help on the forums about an item script, those that reply have no way to know which method or tutorial the original poster (OP) is working from, or may not be familiar with the method specified by the OP. Therefore I am seeing a lot of replies that not only offer little help to the Newbe, but in fact frustrate them even more. So, for the first time (that I know of) I am offering a Tag Based Scripting tutorial based on and uses the default method set forth by Bioware (for NWN1) and Obsidian (for NWN2)

Tag Based Scripting – NWN1: Jump to Tag Based Scripting – NWN2

Tag Based Scripting simply means this – “Run a script that has a name matching the TAG of the item.” In NWN1, the default scripts are in place for Tag Based Scripting, assuming you are up to date on patches. Nothing more is required of you other than writing the item script itself and setting up the item with the correct properties. Walk threw tutorial: (assumes you are familiar with creating new items) Open the toolset and start a newmodule. Just to verify, open the module properties and make sure the following scripts are in place in the events;

Go to the Item blueprint pallet and create a new item, medium thin. Name it “Test Item” and TAG it “TEST_ITEM”. Pick any image you want. In the properties window select “Cast Spell: Unique Power”. Edit the properties and give it “Unlimited Uses Per Day” and check the “Identified” box. Now lets write the script for it. But first lets look at the default “example” item script Bioware offers to us. Open the script editor and then open the script “x2_it_example”, be sure “All Resources” is checked when opening a Bioware script. This script is set up to handle all possible item type scripts. We must check which event triggered the script. Other wise our activate script will trigger when acquired and un-acquired. We only want it to trigger when activated so we must check for that event, and exit the script on all other events. We are making an On Activate item, so the only lines that must be in our item script is line 27, 31, and line 50. Using this example script, we can make templates to use for each event. For example our OnActivate Event script template would be,

////////////////////////////////////////////////////////////////////

// FILE NAME :

// CREATED BY:

// DATE      :

///////////////////////////////////////////////////////////////////

// Modified By :

// Date        :

////////////////////////////////////////////////////////////////////

/*

Notes

/*

#include "x2_inc_switches"

void main()

{

        int nEvent =GetUserDefinedItemEventNumber();             

        // Exit if not an activate event

        if(nEvent !=  X2_ITEM_EVENT_ACTIVATE)return;

        // Your script here

}

Lets save the above script as a template. Simply copy the script into note pad, or some other text editor. Then save the file as a .txt file into the C:\NeverwinterNights\NWN\scripttemplates folder and name it “Event_OnActivate”. Now close and reopen the script editor. Click the “Templates” tab. You should see your new template “Event_OnActivate”. Double Clicking the template will place it in the script editor. Go ahead and make a template for each event, all you need to change is the constant X2_ITEM_EVENT_ACTIVATE to one of the following for the appropriate event.

X2_ITEM_EVENT_ONHITCAST               For the OnHit Cast Spell: Unique power

X2_ITEM_EVENT_EQUIP                         For the OnItemEquip Event

X2_ITEM_EVENT_UNEQUIP                    For the OnItemUnequip Event

X2_ITEM_EVENT_ACQUIRE                    For the OnAquire Event

X2_ITEM_EVENT_UNACQUIRE               For the OnUnAquire Event

X2_ITEM_EVENT_SPELLCAST_AT         For casting a spell on the item

 

Now with all your templates, youdon’t have to try and remember what the switches are each time you want to make a unique item script. If it’s not already, double click your “Event_Activate” template to place it in the script editor. NOTE: Delete the all text in the script editor prior to placing a template. The template will not overwrite what is already there. Now we will make a simple script that will tell you the Name, TAG, and location of an object when the item is used. Copy the following and place it in your template under the line “// Your script here”

// Your script here

object oUser = GetItemActivator();

object oTarget = GetItemActivatedTarget();

string sName = GetName(oTarget);

string sTag = GetTag(oTarget);

location lLoc = GetLocation(oTarget);

vector vPos = GetPositionFromLocation(lLoc);

SendMessageToPC(oUser,"OBJECT NAME: "+sName);

SendMessageToPC(oUser,"OBJECT TAG: "+sTag);

SendMessageToPC(oUser,"OBJECT POSITION: "+FloatToString(vPos.x)+","+FloatToString(vPos.y)+","+FloatToString(vPos.z));

SendMessageToPC(oUser,"OBJECT AREA: "+GetName(GetAreaFromLocation(lLoc)));

 

So your entire script looks like this;

////////////////////////////////////////////////////////////////////

// FILENAME :

//CREATED BY:

//DATE      :

////////////////////////////////////////////////////////////////////

// ModifiedBy :

//Date        :

////////////////////////////////////////////////////////////////////

/*

Notes

*/

#include"x2_inc_switches"

void main()

{

            int nEvent =GetUserDefinedItemEventNumber();

            // Exit if not an activate event

            if(nEvent !=  X2_ITEM_EVENT_ACTIVATE)return;

            // Your script here

            object oUser = GetItemActivator();

            object oTarget = GetItemActivatedTarget();

            string sName = GetName(oTarget);

            string sTag = GetTag(oTarget);

            location lLoc = GetLocation(oTarget);

            vector vPos = GetPositionFromLocation(lLoc);

            SendMessageToPC(oUser,"OBJECT NAME: "+sName);

            SendMessageToPC(oUser,"OBJECT TAG: "+sTag);

            SendMessageToPC(oUser,"OBJECT POSITION: "+FloatToString(vPos.x)+","+FloatToString(vPos.y)+","+FloatToString(vPos.z));

            SendMessageToPC(oUser,"OBJECT AREA: "+GetName(GetAreaFromLocation(lLoc)));

}

Now save the script with the nameof “test_item”. Note that this is the same as the TAG we gave the item during creation. Don’t worry about the case, as it is automatic. Place some placeables around in the starting area to serve as targets for this item (make sure they are marked “Useable” so they can be targeted). Place the item on the ground near the start point and save the module. Load up the mod and test out your item. When you use the item, the cursor should change to a “targeting” arrow. Click on any of your placables and you should receive the Name, Tag, position, and Area name of the placeable object in the chat/server window.

That’s it! That’s all there is too it.

Tag Based Scripting – NWN2: Jump to Tag Based Scripting – NWN1

Tag Based scripting in NWN2 works exactly the same as NWN1 with only 2 small exceptions. I suggest you read over the NWN1 tutorial first unless you are already familiar with how TBS works in NWN1.

Exception1:

The script name MUST be prefixed with “i_” AND suffixed (postfixed) with “_ac” for activate. So in the example in NWN1, our script would need to be named “i_test_item_ac”. The prefix and suffix is in place to provide a sense of security for on line modules that allow local vault players.

Each event has a different suffix (postfix) as follows;

For the OnHit Cast Spell: Unique power       Postfix = “_hc”

For the OnItemEquip Event                           Postfix = “_eq”

For the OnItemUnequip Event                       Postfix = “_ue”

For the OnAquire Event                                 Postfix = “_aq”

For the OnUnAquire Event                            Postfix = “_ua”

For the OnActivate Event                              Postfix = “_ac”

For casting a spell on the item                        Postfix = “_ci”

Exception 2:

The script DOES NOT need to check which event triggered the script. So the templates as described in the NWN1 tutorial are not needed. But there is no harm in leaving them in if importing an item script from NWN1 to NWN2.

Advanced scripters:

Open the default OnModuleLoad event script “x2_mod_def_load”. Scroll down to line 104. There you will see the listed abbreviations needed for the Suffix part of the script name. Lines 106 to 118 defines the prefix that must be used. Here you can change the “i_” prefix to anything you want to use.

Also note that if you comment out line 104 and lines 106 to 118, the TBS works exactly the same as described for NWN1, including the need for the event checking templates.