Wizards of Lua

The Art of Spell Crafting

---

Events - Knowing What Happened

The Events module provides functions for accessing and firing Events.

Here is an overview of the Events functions:

Functions

Below you find short descriptions about each of the functions and some examples about how to use them in your spells.

collect (eventName…) -> EventQueue

The ‘collect’ function creates an EventQueue that collects all Event occurrences of the specified kind(s).

Example

Echoing all chat messages.

local queue = Events.collect("ChatEvent")
while true do
  local event = queue:next()
  spell:execute("say %s", event.message)
end

Example

Posting the position of all block-click events into the chat.

local queue=Events.collect("LeftClickBlockEvent","RightClickBlockEvent")
while true do
  local event = queue:next()
  spell:execute("say %s at %s", event.name, event.pos)
end

fire (eventName, data) -> nil

The ‘fire’ function posts a new CustomEvent with the given name and the optional given content data.

Example

Firing a custom event without any data.

Events.fire("my-event")

Example

Registering an event intereptor for a custom event that prints the event data.

Events.on("my-event"):call(function(event)
  print(str(event.data))
end)

Firing a custom event with some data.

local data = spell.block
Events.fire("my-event", data)

intercept (eventNames, eventHandler) -> EventInterceptor

Creates an event interceptor for Events with the specified names.

The interceptor will be called immediately when an event occurs, which allows events to be modified and canceled.

Event interceptors do not support sleeping - therefor, autosleep is disabled and manual sleeping is treated as an illegal operation.

As long as a Spell has any active event interceptors it will not terminate by itself, so make sure to stop each event interceptor that is no longer needed.

Example

Intercepting chat events.

local interceptor =
Events.intercept({'ChatEvent'}, function(event)
  print(str(event))
end )

Warning: Beware of possible race conditions!

Be careful, when accessing variables that are used both by the main program as well as by the event interceptor.

If autosleep is enabled, the main program can fall asleep eventually at any time, which allows that a variable might be modified in an awkward situation.

For instance, the following program fails due to indexing a nil value in line 10 despite the nil check in line 8.

In this example there is an explicit sleep in line 9, but that sleep could just as well be caused by autosleep.

local abc = 'abc'
local interceptor = Events.intercept({'my-event'}, function(event)
  abc = nil
end)
spell:execute([[lua
  Events.fire('my-event')
]])
if abc ~= nil then
  sleep(1)
  print(abc:len())
end
interceptor:stop()

on (eventName…) -> table

Returns a table containing the specified event names and a reference to intercept. This can be used as shorthand for intercept.

Example

Subscribing for chat events and printing the messages.

local interceptor = Events.on('ChatEvent'):call( function(event)
  print(event.message)
end)