Using Creature Events

Intended Audience:
By David Gaider
[Printer Friendly / Syntax Highlight]
As mentioned previously in the 'UserDefinedEvents Are Your Friend' post, unless you
know exactly what you are doing, it is not advisable to mess with the default AI scripts
that are used on creatures (except for the OnSpawn script, which is what it's there for). It
is perfectly possible to make use of every event listed below by uncommenting the
associated flag in the OnSpawn script and writing an OnUserDefined script to make use
of the associated event number (all the examples below will be OnUserDefined scripts
doing so).
Creature Event Listing
Event: OnPerception, triggered by: something has entered the creature's perception
radius. This does not automatically mean that the creature sees or hears this thing... just
that it is possible for him to perceive it. what triggered it? Use GetLastPerceived() to
return the last perceived creature (whether it was actually seen or not).
Also used here: GetLastPerceptionHeard() returns TRUE or FALSE as to whether the last
perceived object was also heard, GetLastPerceptionInaudible() returns TRUE or FALSE
as to whether the last perceived object has become inaudible, GetLastPerceptionSeen()
returns TRUE or FALSE as to whether or not the last perceived object can be seen,
GetLastPerceptionVanished() returns TRUE or FALSE as to whether or not the last
perceived object can no longer be seen. One thing to remember: all the above commands
relate ONLY to the OnPerception event. Do not use them elsewhere.
What does the default AI script do? The OnPerception generic AI gives priority to first
going into search mode if an enemy has suddenly vanished, then telling the creature to
combat an enemy that has appeared.
Example: I want my human NPC to turn towards anyone he sees, and if they are female
to bow to them.
NWScript:
----------------------//taken from David Gaiders Scripting Lesson 17 Using Creature Events
//placed in OnUserDefined script on NPC
//OnPercieve Flag must be uncommented in NPCs Custom OnSpawn script
//when NPC sees(OnPercieve) a female creature, he turns to face her and bows
void main()
{
int nEvent = GetUserDefinedEventNumber();

// if the OnPerception event was fired

if (nEvent == 1004) // OnPerception event
{
object oTarget = GetLastPerceived();
// and I can see the person in perception range
if (GetLastPerceptionSeen())
{
// put the command to turn towards them in my queue
ActionDoCommand(SetFacingPoint(GetPosition(oTarget)));
}
// and if they are female
if (GetGender(oTarget) == GENDER_FEMALE)
{
// pause for half a second
ActionWait(0.5);
// and then bow
ActionPlayAnimation(ANIMATION_FIREFORGET_BOW);
}
}
}
---------------------

Event: OnSpellCastAt, triggered by: a spell has been cast at the creature... note that
spells don't intrinsically cause this event. You will see in your command list a
'EventSpellCastAt'. The spell scripts specifically use this command on their target to tell
it a spell has been cast... and the command also tells them whether or not the spell is a
hostile one. what triggered it? Use GetLastSpell() to return the constant of the spell used
(SPELL_*).
Also used here: GetLastSpellCaster() to return the object that cast the spell,
GetLastSpellHarmful() returns TRUE or FALSE as to whether or not the event was
marked hostile.
What does the default AI script do? If a harmful spell has been cast on the creature and it
is not currently in combat, it goes hostile.
Event: OnPhysicalAttacked, triggered by: the creature has been attacked in melee, what
triggered it? Use GetLastAttacker(). Also used here(i): GetLastDamager()
(i)What does the default AI script do? If the creature is attacked and not currently in
combat, it goes hostile and emits the appropriate shouts to alert allies nearby.
Event: OnDamaged, triggered by: creature has lost hit points, what triggered it? Use
GetLastDamager().
Also used here[i/]: GetTotalDamageDealt(), GetDamageDealtByType(int

nDamageType), GetCurrentHitPoints(object oObject = OBJECT_SELF),

GetMaxHitPoints(object oObject = OBJECT_SELF)
(i)What does the default AI script do? if the creature was hurt by someone he can't see,
try to find them. Otherwise locate an appropriate target and go hostile.
Example: with this particular creature, if he loses more than half his hit points he will
shout out something, run to a waypoint called "CAVE_EXIT" and disappear.
NWScript:
--------------//taken from David Gaiders Scripting Lesson 17 Using Creature Events
//placed in OnUserDefined script on NPC
//OnDamaged Flag must be uncommented in NPCs Custom OnSpawn script
//when creature drops to less than half of maximum hitpoints, he shouts something, flees
to exit and dissapears
//so, this is a script for a NPC to run for his life when he sees he is losing the fight
void main()
{
int nEvent = GetUserDefinedEventNumber();
if (nEvent == 1006) // OnDamaged event
{
int nMaxHP = GetMaxHitPoints();
int nCurHP = GetCurrentHitPoints();
// if at less than half hit points
if (nCurHP < (nMaxHP / 2))
{
// stop what I'm doing
ClearAllActions();
// cry out loud
ActionSpeakString("Ahhh! Run!!");
// run to the exit
ActionMoveToObject(GetObjectByTag("CAVE_EXIT"), TRUE);
// and destroy myself
ActionDoCommand(DestroyObject(OBJECT_SELF));
// accept no further AI commands from this point
SetCommandable(FALSE);
}
}
}

--------------------

Event: OnDisturbed, trigger: something has either been added to or removed from the
creature's inventory, what triggered it? Use GetLastDisturbed() to return the creature
object who disturbed the inventory.
Also used here: GetInventoryDisturbType() will return either
INVENTORY_DISTURB_TYPE_ADDED,
INVENTORY_DISTURB_TYPE_REMOVED, or
INVENTORY_DISTURB_TYPE_STOLEN, GetInventoryDisturbItem() will return the
object that was either removed or added to inventory.
What does the default AI script do? Since a creature can't have an item added or removed
from its inventory (it's not a container), if it's inventory is disturbed it must have been
stolen... go hostile if there is a valid target.
Event: OnCombatRoundEnd, triggered by: a combat round has ended and this event is
triggered automatically. What does the default AI script do? Unless there is a special
behavior set or the set warnings flag in OnSpawn has been set, a new combat round is
initiated.
Event: OnConversation, triggered by: the creature has been clicked on for conversation
OR someone has audibly spoken, what triggered it? Use GetLastSpeaker() to return the
creature who clicked on them or spoke out loud.
Also used here: GetListenPatternNumber() to return a pattern number if one has been set
up.
What does the default AI script do? If the creature has been clicked on for conversation, it
will stop what it's doing and begin dialogue (if it can). Otherwise the script checks to see
if a spoken phrase is recognizeable and if the creature has been set up to recognize
combat shouts.
Event: OnRested, triggered by: the creature has rested via ActionRest(). Creatures in the
game don't normally rest, so there is no default AI script functions here.
Event: OnDeath, triggered by: the creature has been killed, what triggered it? use
GetLastKiller() to return the object that killed the creature. Note that any scripts that are
run off this event need to be immediate... using DelayCommand will not work as the
creature cannot run commands past the point of its death.
What does the default AI script do? It checks to see if the creature was non-evil and had
Commoner levels... and if so automatically changes the killer's alignment a little towards
evil. It also emits standard shouts for help to any creatures within range who are set up to
listen for them.
Event: OnBlocked, triggered by: a door is blocking the creature's movement, what
triggered it? Use GetBlockingDoor() to return the door object. Note that only doors
currently trigger the OnBlocked event... this is not used for collision detection (yet).

What does the default AI script do? If the creature is smart enough to use a door
(Intelligence of 5+) it will first attempt to open the door and, if that's not possible, will
attempt to bash it down.
Event: OnHeartbeat, triggered by: there is no trigger neeaded for the heartbeat... any
script in this area will be run automatically once every six seconds. It is important that
you do not attach scripts to the heartbeat which will run constantly, as the resulting
overhead (especially if you have a lot of creatures doing so) can be high.
What does the default AI script do? It checks for some conditions that are set in the
OnSpawn and executes them if they are applicable... such as the 'fast buff' for enemies
(used when PC's draw within a certain range), day/night postings for the WalkWayPoints
function and the standard ambient animations used by creatures when standing around.