Event Handler Functions
An event handler is a user-defined function designed to respond to game events. Rather than calling the function directly, the scripter uses SetEventHandler to register it as a handler for a specific event. When the associated event occurs during gameplay, OBSE will invoke any handlers for that event, passing information about the event to the function through its arguments.
Events include block types such as "OnHit", "OnDeath", and so on, as well as other events involving loading, saving, and exiting the game. Each event expects its handlers to accept a specific set of arguments. The supported events, including any required arguments (listed in the order in which they should appear in the function definition) are listed below:
Events
| Event Name String | Parameters | Notes |
| OnHit | target:ref attacker:ref | |
| OnHitWith | target:ref weapon:form | |
| OnMagicEffectHit | target:ref magicEffectCode:string (4 characters) | |
| OnActorEquip | target:ref item:form | |
| OnDeath | target:ref killer:form | |
| OnMurder | target:ref killer:form | |
| OnKnockout | target:ref | |
| OnActorUnequip | target:ref item:form | |
| OnAlarm Trespass | alarmedActor:ref criminal:ref | |
| OnAlarm Steal | alarmedActor:ref criminal:ref | |
| OnAlarm Attack | alarmedActor:ref criminal:ref | |
| OnAlarm Pickpocket | alarmedActor:ref criminal:ref | |
| OnAlarm Murder | alarmedActor:ref criminal:ref | |
| OnPackageChange | target:ref package:form | |
| OnPackageStart | target:ref package:form | |
| OnPackageDone | target:ref package:form | |
| OnStartCombat | target:ref opponent:ref | |
| OnActivate | activatedRef:ref activatingRef:ref | |
| OnVampireFeed | NONE | invoked after player finishes feeding as a vampire |
| OnSkillUp | skillActorValueCode:int | invoked after skill increases through use |
| OnScriptedSkillUp | skillActorValueCode:int amount:int | when ModPCSkill/AdvanceSkill are used to increase skill, invoked before the skill is modified |
| OnDrinkPotion | drinker:ref potion:form | |
| OnEatIngredient | eater:ref ingredient:form | also triggers OnActorEquip event |
| OnActorDrop | dropper:ref droppedItem:ref | droppedItem is the new reference in the game world to the dropped item |
| OnSpellCast | caster:ref spell:form | |
| OnScrollCast | caster:ref scrollEnchantment:form | |
| OnFallImpact | faller:ref | invoked when a falling actor hits the ground with sufficient velocity to be potentially damaging, before damage is applied |
| OnMapMarkerAdd | mapMarker:ref | |
| OnHealthDamage | damage:float attacker:ref | Invoked on the actor taking damage (i.e. GetSelf will return the damaged actor) whenever damage is taken. "Attacker" may be zero e.g. when taking damage from falling. The handler is invoked just before the damage is applied, so it can be nullified by commands like ModActorValue. Use the object filter to specify the damaged actor to which your event handler should be attached, if any. |
| OnCreateSpell | spell:ref | when player creates a new spell |
| OnCreatePotion | potion:ref isUnique:int | when player creates a new potion. The second argument is 1 if the resulting potion is a new base object, 0 if a previously-created potion has the same effects as the newly-created one (in which case the existing base object is used). |
| OnEnchant | enchantedItem:ref | when player enchants an item. |
| OnAttack | actor:ref | Slightly misnamed. Invoked whenever actor begins the animation sequence for a melee or staff attack or a spell cast. Use commands like IsCasting to determine the current action. |
| OnBowAttack | actor:ref | actor begins the animation of drawing his bowstring |
| OnRelease | actor:ref | animation begun by OnAttack or OnBowAttack completes - e.g., actor releases an arrow shot, swings his weapon, or releases a spell projectile. |
| OnBlock | actor:ref | actor begins block animation |
| OnRecoil | actor:ref | actor begins recoil animation |
| OnStagger | actor:ref | actor begins stagger animation |
| OnDodge | actor:ref | actor begins dodge animation |
| LoadGame | filename:string | |
| SaveGame | filename:string | |
| PostLoadGame | gameLoadedSuccessfully:bool | 0 if error occurred during load (corrupt savegame?), 1 otherwise |
| ExitGame | NONE | exiting from main menu or in-game menu |
| ExitToMainMenu | NONE | exiting from in-game menu to main menu |
| QQQ | NONE | exiting via QQQ/QuitGame console command |
| OnNewGame | NONE | user starts a new game from the main menu |
For events associated with block types, you may provide a specific value for any, all, or none of the arguments when registering an event handler. The first argument is referred to by the name "ref" and the second as "object", regardless of the names of the argument variables in your function script (exception: for OnHealthDamage, "object" refers to the damaged actor). Doing so allows you to filter out events you're not interested in.
For instance, to handle events involving the player being hit by another actor, use:
SetEventHandler "OnHit", yourScript, ref::playerRef
To handle events in which the player, and only the player, hits anyone else, use:
SetEventHandler "OnHit", yourScript, object::playerRef
To handle the player being affected by a Restore Health magic effect, use:
SetEventHandler "OnMagicEffectHit", yourScript, ref::playerRef object::"REHE"
Notes
- Avoid using AddSpell to add an ability or disease to an actor from within an OnMagicEffectHit handler, as doing so may cause the game to become unstable.
- Event handler scripts are invoked at the moment the event is registered by the game. For example, an "OnEquip" handler is invoked when an actor decides to equip an item, but before the item is actually equipped, which means that trying to unequip the item from within the handler will fail.
- It is recommended that you prefer to filter events as strictly as possible to allow OBSE to avoid calling your handler for events you're not interested in. Further, once an event handler becomes unneeded (for instance, if the target of the handler dies), use RemoveEventHandler to remove it; this prevents OBSE from having to check against the defunct handler when processing events.