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:
eventId
(string, tes3.event): Optional.filter
(userdata, string, number, tes3baseObject): Optional.
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 totrue
, 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 totrue
, the registered function will be unregistered when the nextload
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. Returningtrue
from a callback function will set bothpayload.block
andpayload.claim
totrue
. After an event has been claimed by a certain function (by setting theclaim
in eventData totrue
) 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 theeventData
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 toevent.unregister
to successfully unregister the callback function.