Home For Builders Scripting Tutorials Using Creature Events

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:
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:
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.