SetEventHandler

A command for Oblivion Script Extender

Syntax:

(success:bool) SetEventHandler eventID:string functionScript:ref filter1:pair filter2:pair

Registers a user-defined function script as a handler for the specified event. If the user-defined function script returns a value, it will be ignored.

Two optional arguments can be supplied to SetEventHandler by using the unique syntax of "key"::value pairs to filter events according to the target and/or object. The "key" part is a string (must be enclosed in quotes) and is generally expected to be either "ref" (generally referring to the target or first argument in your custom function) or "object" (generally referring to the source or second argument in your custom function), regardless of the names of the argument variables in your function script (exception: for OnHealthDamage, "object" refers to the damaged actor).

For more details on events and for a list of available events to hook into, see Event Handler Functions.

Example

User Function Script #1

	scn FnOnHitByPlayer
	ref target
	ref attacker
	
	begin Function { target, attacker }
		attacker.PushActorAway target, 50
	end

User Function Script #2

	scn FnOnPlayerRestoreHealth
	ref target
	long effectCode
	
	begin Function { target, effectCode }
		; expecting effectCode to be "REHE"/restore health
		message "The player has been hit by a restore health effect"
	end

User Function Script #3

	scn FnOnLoadGame
	string_var filename
	
	begin Function { filename }
		print "Loading game from " + $filename
	end

Primary Script

	scn SomeQuestScript
	begin gamemode
		if getGameRestarted
			SetEventHandler "OnHit" FnOnHitByPlayer "object"::Player
			SetEventHandler "OnMagicEffectHit" FnOnPlayerRestoreHealth "ref"::Player "object"::"REHE"
			SetEventHandler "LoadGame" FnOnLoadGame
		endif
	end

With the the above four scripts compiled and loaded and the quest script SomeQuestScript activated, you should then see the following new effects in game:

1. Whenever the player hits another actor, that actor will be knocked back 50 feet/units.
2. Whenever the "REHE" magic effect is applied to the player, you should see a message: "The player has been hit by a restore health effect"
3. Whenever a game is loaded, you should see a console message: "Loading game from filename"

Notes

none

See Also

• RemoveEventHandler
• GetCurrentEventName
• Event Handler Functions
• User Functions