New xNVSE Event Filtering System

From GECK
Jump to: navigation, search

Intro

Since xNVSE 6.2.8, a new way to filter events was made for SetEventHandlerAlt, which allows multiple filters of any type, such as numbers, forms, strings, and arrays.

This is in contrast with the Old Event Filtering System used by SetEventHandler, which only allows up to 2 form filters.

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

  • This is to support array-type filters, since array_vars are save-baked, and loading back to a previous save could invalidate a previously set handler if it had an array filter.

The information below describes how different filter types are handled. In addition, array-of-filters filters are allowed.

Basic Filter Types

Numeric (Int/Float) Filter

For numeric-type filters, the dispatched number must match the numeric filter for the handler to be executed.

If the event for the filtered handler is User-Defined, and a numeric filter is passed, that filter will be assumed to be a float.

Otherwise, plugin-defined events have the choice between defining a filter as int or float-type. If int-type, then all numbers passed as filters will be treated as ints, even if they were floats (the float will be Floored).

Form (Ref Variable) Filter

By default, will try to match the dispatched form directly with the form filter.

  • Both forms could be null, and they would still match.

In case a reference is dispatched, it can be filtered by a BaseForm.

All form-type filters support FormList filters, which will check if the dispatched form matches with any of the forms in the list.

Reference Filter

Behaves the same as a generic form-type filter. Exists to clarify that the dispatched form will always be a reference (or possibly a null form).

BaseForm Filter

Exists to clarify that the dispatched form will always be a baseform. Will throw an error if trying to set a reference as a BaseForm filter.

String Filter

Will check if the filter string and the dispatched strings are equal. Case-insensitive.

Array Filter

Will compare the array filter with the dispatched array, comparing the elements of each array for equality. They must also be of the same size and array type to match.

  • NOTE: Multidimensional array filters are not currently supported.

Array of Filters

Just like how a FormList can be used for a form-type filter to check if any of the forms in the list match with the dispatched form, array-of-filters filters can be set to look through multiple elements in that array.

Array-of-filters filters can be regular arrays, StringMaps or even Maps. In the latter two cases, keys will be ignored.

For example, if an event dispatches a string argument, instead of being limited to checking if it matches with only one string, we can set an array-of-filters containing multiple strings. This way, if the string arg matches with any of the strings in the array, then

Array-of-filters store a reference to an existing array. This means that after setting an array-of-filters filter via SetEventHandlerAlt, that array can be modified at any time in the future, and the event will be filtered according to those changes.

See Also

Retrieved from "https://geckwiki.com/index.php?title=New_xNVSE_Event_Filtering_System&oldid=32171"