Skip to content

event⚓︎

The event library helps to instruct mwse to call a given function when a specific action is taken in the game.

Functions⚓︎

event.clear⚓︎

Removes all callbacks registered for a given event.

event.clear(eventId, filter)

Parameters:

event.isRegistered⚓︎

Returns true for a function previously registered to an event with event.register().

local result = event.isRegistered(eventId, callback, { filter = ... })

Parameters:

  • eventId (string, tes3.event)
  • callback (function)
  • options (table): Optional.
    • filter (userdata, string, number, tes3baseObject): Optional. Allows searching for a callback function registered with the specified filter.

Returns:

  • result (boolean)

event.register⚓︎

Registers a function to be called when an event is raised.

event.register(eventId, callback, { doOnce = ..., filter = ..., priority = ..., unregisterOnLoad = ... })

Parameters:

  • eventId (string, tes3.event)
  • callback (function)
  • options (table): Optional.
    • doOnce (boolean): Default: false. If this option is set to true, the function registered will be executed only once, and automatically unregistered thereafter.
    • filter (userdata, string, number, tes3baseObject): Optional. This parameter allows selectively executing the callback function only when a specific condition is met. The exact behavior depends on each event.
    • priority (number): Optional. Event callback with higher priority is executed before callback with lower priority. Typically used to make certain mods compatible.
    • unregisterOnLoad (boolean): Default: false. If this option is set to true, the registered function will be unregistered when the next load event triggers.

event.trigger⚓︎

Triggers an event. This can be used to trigger custom events with specific data.

local resultPayload = event.trigger(eventId, payload, { filter = ... })

Parameters:

  • eventId (string, tes3.event)
  • payload (table): Optional.
  • options (table): Optional.
    • filter (userdata, string, number, tes3baseObject): Optional. Assigning a filter will make the event callbacks with filters matching this one to be executed first. All the other unfiltered callbacks are executed after.

Returns:

  • resultPayload (table): This is the modified payload after all the callback functions registered on the triggered event are executed. Returning true from a callback function will set both payload.block and payload.claim to true. After an event has been claimed by a certain function (by setting the claim in eventData to true) no other registered callback functions will be executed on this event trigger. This is useful if you wish to implement blocking system for your event. In addition, this can be used to the same effect as some MWSE's events allow changing some of the eventData values to modify the behavior of the vanilla mechanics.
Example: Custom event with e.block support 
-- Definition for my custom event eventData table
--- @class myCustomEventData
--- @field count integer
--- @field item tes3item
--- @field itemData tes3itemData|nil
--- @field equipped boolean

--- @param e myCustomEventData
local function doMyCustomLogic(e)
    -- We can do some logic accounting for the changes callbacks made in the eventData table.
    -- ...
end

local function somethingHappened()
    -- Assemble the eventData table
    --- @type myCustomEventData
    local e = {
        count = 1,
        item = tes3.getObject("myItemId") --[[@as tes3misc]],
        itemData = nil,
        equipped = false
    }

    -- First we trigger the pre-event that supports blocking our logic from happening.
    local eventResult = event.trigger("myMod:myCustomEvent", e, { filter = e.item.id:lower() })

    -- Was the event blocked by one of the callbacks?
    if eventResult.block then
        -- Nothing to do then :)
        return
    end

    doMyCustomLogic(eventResult)

    -- We have to reset these fields to be able to reuse
    -- eventResult table in the next call to event.trigger
    eventResult.block = nil
    eventResult.claim = nil

    -- Now we can trigger off the post-event
    event.trigger("myMod:postMyCustomEvent", eventResult, { filter = eventResult.item.id:lower() })
end

event.unregister⚓︎

Unregisters a function previously registered for an event with event.register().

event.unregister(eventId, callback, { filter = ... })

Parameters:

  • eventId (string, tes3.event)
  • callback (function)
  • options (table): Optional.
    • filter (userdata, string, number, tes3baseObject): Optional. If a callback function was registered with a filter, the same filter needs to be passed to event.unregister to successfully unregister the callback function.