Home For Builders Scripting Tutorials The Userdefined Event Is Your Friend

The Userdefined Event Is Your Friend

Intended Audience:
By David Gaider

[Printer Friendly / Syntax Highlight]

Seriously. No joke at all here. There will naturally be some users who will prefer to go deeper and customize the various scripts that make up the generic AI... some will even go further than that and come up with their own versions of the generic AI include file. That's great, and there's nothing wrong with doing that.

The great thing is: you don't have to. 98% of the creature scripting that was done in the NWN official campaign was done using UserDefinedEvents. I sat down with Preston (one of our scripters and one of the main guys behind the generic AI) and fired off a rapid series of things I would like to script... just about every one was do-able using the UserDefinedEvent. And it is easy to implement.

Let's back up for a second here and discuss what an event is. Basically there are numerous scripts (sets of instructions) that exist on a creature... and each one is tied to events. When an event occurs, it tells the creature to fire off the proper script. No event = the script doesn't run.
There are a number of events which get mentioned here a lot. The 'OnHeartbeat' event fires every 6 seconds... so the script attached to that even runs that often. The 'OnPerceived' event fires whenever the NPC perceives anything... the script attached gets run. These scripts can even fire off other events, prompting different scripts to be run... and therein lies the UserDefinedEvent.

Basically, the UserDefinedEvent allows you to access the normal events a creature uses (OnPerception, OnDeath, etc.) without disturbing the normal AI routines or modifying the already-existing scripts.

Using the UserDefinedEvent
There is one script on every creature that has been mentioned lots before, and it's one you will get to know well. This is the OnSpawn script. This is an event that runs only once when the creature first comes into existence... think of it as an 'initializing' script.

The generic OnSpawn script has a whole series of commands in it which are commented out... as a matter of fact, without the user changing anything in it, all that large script really does is three commands: it tells the creature to walk waypoints that refer specifically to its tag, set up its listening patterns (so it will respond to shouts from other NPC regarding combat) and generate a small amount of generic treasure in inventory (some gold, etc.)

It is designed to allow the user to set states that access the generic AI, as they wish. All they do is go through the list and uncomment any state flags they wish to use (remove the '//' double slashes at the beginning of the command). Then save the OnSpawn script under a different name and use it in place of the regular one... voila, the generic behaviors have been altered.

The state flags we need to pay attention to are these:

SetSpawnInCondition (NW_FLAG_PERCIEVE_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1002

SetSpawnInCondition (NW_FLAG_ATTACK_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1005

SetSpawnInCondition (NW_FLAG_DAMAGED_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1006

SetSpawnInCondition (NW_FLAG_DISTURBED_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1008

SetSpawnInCondition (NW_FLAG_END_COMBAT_ROUND_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1003

SetSpawnInCondition (NW_FLAG_ON_DIALOGUE_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1004

SetSpawnInCondition (NW_FLAG_DEATH_EVENT);
//OPTIONAL BEHAVIOR - Fire User Defined Event 1007

What Next?

Okay... you've uncommented the flags you want to script for and re-saved the OnSpawn script. That's taken you 2 minutes. Now how do you use it?

Every creature has an OnUserDefined event section that you can put a script in. For any creature you make, it will be completely blank... this is where you do your actual scripting. Any script you put here will be 'checked' every time an event of the type you uncommented occurs. So if you uncomment the 'SetSpawnInCondition (NW_FLAG_DISTURBED_EVENT)', then every time the creature's inventory was disturbed (say someone pickpockets an item), the OnUserDefined script would also be run.

The basic OnUserDefined script would look similar to this:

NWScript:
void main() { int nUser = GetUserDefinedEventNumber(); if (nUser == the number in the OnSpawn, from 1001 to 1007) { (do something) } }

Let's say I want to make a creature wave to the first PC that he sees. I go into the OnSpawn an uncomment 'SetSpawnInCondition (NW_FLAG_PERCIEVE_EVENT)' and then re-save it as a new script.

Then I create a script for the OnUserDefined perhaps as so:

NWScript:
// this script will make the NPC wave to a PC upon perceiving them // remember that if the PC starts off the module in the NPC's perception // range, no event will fire (because perception has not changed) void main() { int nUser = GetUserDefinedEventNumber(); if (nUser == 1002) // OnPerception event { object oCreature = GetLastPerceived(); int nWave = GetLocalInt(OBJECT_SELF, "Wave_Once"); //check to see if I actually saw a PC if (GetLastPerceptionSeen() && GetIsPC(oCreature) && (nWave == 0)) { // wave only once SetLocalInt(OBJECT_SELF, "Wave_Once", 1); // set a timer so that the NPC can wave again 15 seconds later DelayCommand(15.0, SetLocalInt(OBJECT_SELF, "Wave_Once", 0)); // turn to face the PC ActionDoCommand(SetFacingPoint(GetPosition(oCreature))); // wave howdy ActionPlayAnimation(ANIMATION_FIREFORGET_GREETING); SpeakString("Hello!"); } } }

And that's it. I could also set other checks like a minimum distance, see if the PC is facing me... or get as complex a behavior as I wish... and I don't have to worry about screwing up the AI scripting that's already sitting in the OnPerceive event section.