SetEventHandlerAlt

A function added by the New Vegas Script Extender version 6.2.8.

Description

Allows up to 16 value filters of any type (numeric, form, string, array), as well as array-of-filters filters. Also allows specifying the event handler's priority amongst other handlers, more information in the Priority System section.

Details on how filter types are handled are available here: New xNVSE Event Filtering System.

CAUTION: All event handlers registered with this function will be cleared/flushed on load.

LN events CANNOT be used with this function, since xNVSE does not directly manage those events. For example, OnCellEnter is an invalid event to use for this function.

Each filter arg is a pair. In this case, the numeric index of the nth argument to filter is paired with the actual filter. Example:

1::"I am a string filter"

Assuming that the first arg dispatched is a string, then this will filter that arg; if the two strings match, then this event handler is dispatched, otherwise it isn't.

Index 0 is a special case; it is reserved to filter the calling reference, also known as what is returned by GetSelf / GetSelfAlt.

The other 15 value filters (indexes 1-15) are for filtering the args that are passed.

Lastly, a priority value can be specified, see the Priority System section for more information.

Multiple event handlers can be set for the same script UDF, though one should avoid having redundant handlers, otherwise the handlerFunction could be called multiple times for the same event dispatch.

To remove these handlers, use RemoveEventHandler, which now supports numeric-type arg indexes.

Like SetEventHandler, this works with User-Defined Events, which can be dispatched via DispatchEvent and DispatchEventAlt.

Syntax

[help]

(success:bool) SetEventHandlerAlt eventName:string handlerFunction:UDF filters(up-to-16):pair priority:pair{"priority"::1}

Example

scn OnHitUDF
begin Function { ref rTarget, ref rAttacker }
    printvar rTarget
    printvar rAttacker 
    print "OnHitUDF >> RAN!"
end

The following code uses the OnHit NVSE event.

SetEventHandlerAlt "OnHit" OnHitUDF
; Unfiltered, so OnHitUDF will run whenever the NVSE OnHit event is fired.

SetEventHandlerAlt "OnHit" OnHitUDF 1::Player
; The 1st arg is filtered, so OnHitUDF will only run if rTarget is the player.

SetEventHandlerAlt "OnHit" OnHitUDF 2::SunnyREF
; The 2nd arg is filtered, so OnHitUDF will only run if rAttacker is SunnyREF.

SetEventHandlerAlt "OnHit" OnHitUDF 1::Player 2::SunnyREF
; The 1st and 2nd args are filtered, so OnHitUDF will only run if rTarget is the player and rAttacker is SunnyREF.

SetEventHandlerAlt "OnHit" OnHitUDF 1::(Ar_List Player, SunnyREF)
; The 1st arg is filtered, so OnHitUDF will only run if rTarget is either the player or SunnyREF.

scn NVSELoadGameUDF
begin Function { string_var sSaveFileName }
    printvar sSaveFileName
    print "NVSELoadGameUDF >> RAN!"
end

The following code uses the LoadGame NVSE event.

SetEventHandlerAlt "LoadGame" NVSELoadGameUDF 1::"Save 185   c69  Primm  01 54 17.fos"
; The 1st arg is filtered, so NVSELoadGameUDF will only run if sSaveFileName is equal to that string.

Priority System (New in xNVSE 6.2.9)

If unspecified, default priority while setting an event is 1.
Highest (greatest) priority means the handler will run first before other handlers, lowest means it will run last.
Handlers on the same priority will execute based on registration order. To debug priority conflicts, use IsEventHandlerFirst / IsEventHandlerLast.

0 is reserved as an invalid priority, for use in other functions where we don't want to filter by priority.
It cannot be used for this function, as you must register a handler with a valid priority.
Besides that, any number, even a negative number, can be used as a priority.

For more details, see Event Handler Priority System.

Examples for how to specify priority:

SetEventHandlerAlt "SomeEvent" SomeUDF "priority"::2

Will set an event handler with priority 2, which will be guaranteed to execute sooner than any handler that didn't specify a priority.

The priority arg can be swapped around with the filter args. For example, these lines do the same thing:

 SetEventHandlerAlt "SomeEvent" SomeUDF "priority"::2 1::Player
 SetEventHandlerAlt "SomeEvent" SomeUDF 1::Player "priority"::2 

See Also

• SetEventHandler - uses the old filtering system.
• NVSE Event Handling
• RemoveEventHandler - works with both the old and new filtering system.
• GetCurrentEventName
• DispatchEvent / DispatchEventAlt