Пользовательские дополнения

На главную

common.RegisterEventHandler( eventFunction, sysEventName, params, requireMainThread )

Подписывает обработчик аддона на указанное событие. На одно событие может быть несколько обработчиков. Функция-обработчик принимает один параметр - таблицу или целое число - идентификатор объекта от которого нужно получать события.

Также обработчику можно сопоставить параметры params. Это фильтр, представленный таблицей. Когда инициируется скриптовое сообщение, и обработка доходит до данного зарегистрированного обработчика, то проверяется, что в инициированном сообщении имеются точно такие же поля, точно с такими же значениями, что и в фильтре. И только в этом случае управление передаётся обработчику.

params - необязательный параметр метода(если исключения, читай ниже), то есть его можно вообще не указывать. В этом случае поля сообщения не будут проверяться на соответствие для такого обработчика и управление перейдёт в него в любом случае, при любых параметрах сообщения.

Для следующих событий '''params''' является обязательным параметром, в котором должен быть указан идентификатор интересующего объекта ObjectId(number):

• EVENT_HEALING_RECEIVED

• EVENT_UNIT_MANA_PERCENTAGE_CHANGED

• EVENT_UNIT_DAMAGE_RECEIVED

• EVENT_DEVICE_DAMAGE_RECEIVED

• EVENT_OBJECT_BUFFS_CHANGED

• EVENT_OBJECT_BUFF_ADDED

• EVENT_OBJECT_BUFF_REMOVED

• EVENT_OBJECT_HEALTH_CHANGED

Для common.RegisterEventHandler() есть обратный метод common.UnRegisterEventHandler(). Если от обработчика сообщения необходимо отказаться, то ему нужно передать такие же params, как и при регистрации.

Также можно отказаться от любой обработки сообщения с помощью common.UnRegisterEvent( sysEventName ).

-- библиотека:
common

-- объявление:
function RegisterEventHandler( eventFunction, sysEventName, params, requireMainThread )

-- параметры:
eventFunction: function - функция-обработчик
sysEventName: string - название события
params: table or ObjectId(number) or nil - необязательный параметр (можно опустить) с таблицей описывающей фильтр сообщения или идентификатор объекта
requireMainThread: boolean or nil - необязательный параметр, указывает клиенту на то, что при обработке события будет вызван "непотокобезопасный" код и событие нужно обработать в основном потоке; для аддонов разработчиков по умолчанию false; для аддонов пользователей всегда true.

-- возвращаемые значения:
нет

-- прототип функции-обработчика:
function OnEventHandler( params )

-- параметры OnEventHandler:
params: table - параметры события

-- возвращаемые значения OnEventHandler:
нет

-- примеры:
function OnEventSample( params )
end

function OnEventSampleMainPlayer( params )
end

function OnEventSampleObjectInMainThread( params )
end

common.RegisterEventHandler( OnEventSample, "EVENT_SAMPLE" )
common.RegisterEventHandler( OnEventSampleMainPlayer, "EVENT_SAMPLE", { unitId = avatar.GetId() } ) -- обрабатывать сообщения только от главного игрока
common.RegisterEventHandler( OnEventSampleObjectInMainThread, "EVENT_SAMPLE", avatar.GetId(), true ) -- обрабатывать сообщения только от главного игрока и только в основном потоке

Про "основной поток".

В общем случаи нет необходимости подписываться на обработку события в основном потоке. Подписываться на основной поток следует лишь в случаях, когда клиент во время тестирования и отладки явно сообщает, что во время обработки события был вызван код для исполнения которого требуется "основной поток". Пример:

FATAL assert: This call allow only from the main thread
FATAL assert: addon 'ChangeRoom': script event 'EVENT_CHANGE_ROOM_STARTED' (handler: 93) execution require main thread

Соотвественно при регистрации обработчика указанного события(EVENT_CHANGE_ROOM_STARTED) нужно передать параметр '''requireMainThread''' равным '''true''', для исполнения кода обработчика в основном потоке.

Замечание, касающееся пользовательских аддонов.

Так как на боевой версии клиента отсутствуют отладочные сообщения, известить как-то игроков, о том что код обработчика события должен быть исполнен в основном потоке - возможности нет. Поэтому все обработчики событий аддонов, написанных пользователями, всегда исполняются в основном потоке, вне зависимости от значения параметра '''requireMainThread'''.

Search: "CategoryLuaApi" "CategoryCommon"

На главную