Skip to content

EventQueue

Represents a queue that collects and manages events, providing methods to access the latest event, wait for the next event, or stop collection.

An event queue provides access to collected events that have already happened, so it doesn't get a canceled event. To get a callback while an event is happening, so that it can be canceled (if supported), use an EventInterceptor.

Example: Greeting every player who joins

local queue = spell:collect("PlayerJoinedEvent")
while true do
  local event = queue:next() --[[@as PlayerJoinedEvent]]
  spell:execute("/say Welcome, " .. event.player.name .. "!")
end

Example: Collecting events with different names

A queue collects any number of event names, and hands out their events in the order they happened. name tells them apart.

local queue = spell:collect("PlayerJoinedEvent", "PlayerDisconnectedEvent")
while true do
  local event = queue:next()
  if event.name == "PlayerJoinedEvent" then
    ---@cast event PlayerJoinedEvent
    spell:execute("/say " .. event.player.name .. " is here!")
  elseif event.name == "PlayerDisconnectedEvent" then
    ---@cast event PlayerDisconnectedEvent
    spell:execute("/say " .. event.player.name .. " has left.")
  end
end

Fields

empty: boolean — Read-Only

Returns true if the queue contains no events.

names: string[ ] — Read-Only

The names of the events that this queue is collecting.

Methods

latest() → event: any

Returns the newest event in this queue and discards all older events. If the queue is empty, nil is returned. Use this method when only the most recent event is relevant, such as in updates.

Example

local queue = spell:collect("ChatMessageEvent")
while true do
  local event = queue:latest()
  if event ~= nil then
    spell:execute("/say " .. event.message)
  end
  sleep(5 * 20)
end

Returns

  • event: any — The latest event or nil if the queue is empty.

next(timeout?: number) → event: any

Returns the next event in the queue, blocking until an event is available or the specified timeout (in game ticks) is reached. If no timeout is provided, this method blocks indefinitely until an event is available.

Example

local queue = spell:collect("ChatMessageEvent")
while true do
  local event = queue:next()
  spell:execute("/say " .. event.message)
end

Parameters

  • timeout?: number — Timeout in game ticks. If omitted, blocks indefinitely.

Returns

  • event: any — The next event or nil if the timeout is reached.

stop()

Stops the queue from collecting events, preventing further additions to it.

Example

local respawnQueue = spell:collect("AfterPlayerRespawnEvent")
spell:intercept("ChatMessageEvent", function(evt)
  if evt.message == "stop" then
    respawnQueue:stop()
  end
end)
while true do
  local evt = respawnQueue:next(10)
  if evt then
    print(evt.newPlayer.name.." respawned")
  end
end