OnDamaged

The script attached to this event fires when the object is damaged.

Trigger

Creature, door, or placeable object has lost hit points, apart from instant death.

Function(s)

GetLastDamager() returns the object that last dealt damage to OBJECT_SELF, causing this event to fire.
GetTotalDamageDealt() returns the amount of damage dealt to a creature (returns 0 when used in a Door's or Placeable Object's OnDamaged event).
GetDamageDealtByType(int nDamageType) returns the amount of damage dealt by particular attacks.
GetCurrentHitPoints(object oObject = OBJECT_SELF) can be used to return the current hit points of the caller.
GetMaxHitPoints(object oObject = OBJECT_SELF) can be used to return the maximum hit points (and used with GetCurrentHitPoints(object oObject = OBJECT_SELF) for determining how threatened the creature is with death).
DetermineCombatRound(object, int) for standard combat actions.

Remarks

If a creature was hurt by someone they cannot see, they attempt to search for the attacker; if they can see their attacker, they locate the target and attack it.

Known Bugs

GetDamageDealtByType will only return damage amounts for EffectDamage, and so no phisical attack damage will be picked up.

Example

// place in a creature's OnDamaged event
// when the creature loses more than half of his hit points, he 
// will retreat to a waypoint tagged "CAVE_EXIT" and disappear 
void main()
{
     int nEvent = GetUserDefinedEventNumber();
     if (nEvent = 1006) // OnDamaged event 
     {
          int nMaxHP = GetMaxHitPoints(); // OBJECT_SELF (the caller) is default
          int nCurHP = GetCurrentHitPoints(); // OBJECT_SELF (the caller) is default
          // if less than half of maximum
          if (nCurHP < (nMaxHP / 2))
          {
               // stop whatever the creature is doing
               ClearAllActions();
               // cry out in fear
               ActionSpeakString("I'm being violated!");
               // get the hell outta Dodge
               ActionMoveToObject(GetObjectByTag("CAVE_EXIT"), TRUE);
               // destroy itself (simulate a clean getaway)
               ActionDoCommand(DestroyObject(OBJECT_SELF));
               // accept no further AI commands (destroyed!)
               SetCommandable(FALSE);
          }
     }
}