events

Модуль events подписывает функции скрипта на события игры и API и позволяет рассылать свои события. Обращение events.<имя> по любому имени возвращает объект события.

Общие правила#

• Порядок вызова. Подписчики вызываются в порядке подписки, общем для всех скриптов. Приоритетов нет.
• Повторы. Если подписать одну и ту же функцию дважды, она будет вызываться дважды.
• Подписка внутри колбэка. set и unset внутри колбэка не влияют на текущую раздачу: список подписчиков копируется перед вызовом.
• Результат колбэка игнорируется у всех событий, кроме mouse_input.
• Ошибка в колбэке выводится в консоль. Скрипт продолжает работать, подписка остаётся, раздача переходит к следующему подписчику.
• Выгрузка скрипта снимает все его подписки.
• Регистр букв в имени важен: events.Render и events.render — разные события.

Некоторые события игра порождает в других потоках. Такие события ставятся в очередь и приходят скрипту в начале следующего кадра, в исходном порядке. Это помечено в описании события.

events.<name>#

Возвращает объект события с именем name. Список допустимых имён не ведётся: подписаться можно на любое имя, в том числе на своё.

Возвращает: event — объект события. Два объекта с одним именем равны по ==.

local ev = events.render
print(tostring(ev))                         --> event<render>
print(events.render == events.render)       --> true

Присваивание events.<имя> = значение не создаёт и не меняет событие: оно кладёт значение в таблицу events вашего скрипта, и после этого events.<имя> возвращает это значение вместо объекта события. Присвоение nil возвращает объект события. Таблицы events других скриптов это не затрагивает.

events.my_event = 1
print(events.my_event)   --> 1
events.my_event = nil
print(events.my_event)   --> event<my_event>

event:set(fn: function)#

Подписывает функцию fn на событие.

Возвращает: ничего.

local frames = 0

events.render:set(function()
    frames = frames + 1
end)

utils.schedule(5, function()
    print("Кадров за 5 секунд: ", frames)
end)

event:unset(fn: function)#

Снимает все подписки этого скрипта на событие с той же функцией. Подписки других скриптов не трогаются. Если подписки нет, ничего не происходит.

Возвращает: ничего.

-- Колбэк, который сработает только один раз
local function first_frame()
    print("Первый кадр после запуска")
    events.render:unset(first_frame)
end

events.render:set(first_frame)

event(fn: function, enable?: boolean)#

Краткая форма подписки. enable == false снимает подписку (как unset), в остальных случаях подписывает (как set). По умолчанию enable = true.

Возвращает: ничего.

local function on_hurt(e)
    print("player_hurt: урон ", e.dmg_health)
end

events.player_hurt(on_hurt)          -- подписка
-- ...
events.player_hurt(on_hurt, false)   -- отписка

event:fire(...)#

Сразу вызывает всех подписчиков события с переданными аргументами. Работает для любого имени. Удобно для связи частей скрипта или нескольких скриптов.

• Управление возвращается после вызова всех колбэков.
• Ошибки колбэков выводятся в консоль и в вызывающий код не передаются.
• Между скриптами fire тоже работает: подписчики из других включённых скриптов получают те же аргументы. Глобальные переменные у скриптов раздельные, поэтому событие — простой способ передать данные соседнему скрипту.
• Событие получают только те подписчики, которые уже подписались к моменту вызова: если соседний скрипт загружается позже, прошлые вызовы fire до него не дойдут.

Возвращает: ничего.

-- Своё событие: «цель сменилась»
events.my_target_changed:set(function(name, hp)
    print("Новая цель: ", name, " (", hp, " HP)")
end)

events.my_target_changed:fire("enemy", 100)

-- Скрипт A: отправляет данные
events.render:set(function()
    local me = entity.local_pawn()
    if me then events.shared_my_hp:fire(me:health()) end
end)

-- Скрипт B: получает данные
events.shared_my_hp:set(function(hp)
    print("HP из скрипта A: ", hp)
end)

tostring(event)#

Возвращает: string — строку event<имя>.

print(tostring(events.shutdown))   --> event<shutdown>