Event Handler Functions

An event handler is a user-defined function designed to respond to game events. Rather than calling the function directly, you use SetEventHandler to register your user defined function as a handler for a specific event. Then, when ever the associated event occurs during gameplay, OBSE will invoke your script, passing information about the event to your 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.

See Also

• SetEventHandler
• RemoveEventHandler
• GetCurrentEventName
• User Functions
• OBSE Events Documentation