Manipulação de eventos

Eventos são a forma como o servidor avisa que algo aconteceu. Você registra um manipulador com addEventHandler e o servidor chama a sua função quando o evento dispara. Além dos eventos internos, você pode criar os seus próprios com addEvent.

A referência de eventos lista os eventos internos e os argumentos de cada um.

Estas 8 funções existem no servidor e no cliente. Você pode usá-las em scripts declarados em server_files, client_files ou shared_files.

Veja também as funções de Eventos exclusivas do servidor.

Globais dentro de um manipulador

Enquanto o seu manipulador roda, cinco globais ficam preenchidas:

Global	Conteúdo
source	O elemento que originou o evento.
client	O jogador que enviou o evento, quando ele veio do cliente. nil para eventos disparados no próprio servidor.
eventName	O nome do evento em execução.
sourceResource	O resource cujo script chamou triggerEvent. nil quando quem disparou foi a engine ou a rede.
sourceResourceRoot	O elemento raiz desse resource, nil nos mesmos casos.

source, client e eventName valem nil fora de um manipulador — inclusive dentro de um timer ou de uma função exportada chamada por outro resource. sourceResource e sourceResourceRoot são a exceção: dentro de uma função exportada eles apontam para o resource que chamou. Se precisar do valor mais tarde, copie para uma variável local:

addEventHandler("onPlayerJoin", root, function()
    local jogador = source
    setTimer(function()
        outputDebugString(getPlayerName(jogador) .. " está aqui há 3s")   -- `source` já seria nil aqui
    end, 3000, 1)
end)

Cuidado

source é o elemento que originou o evento; client é quem mandou o pacote. Em um evento vindo do cliente, source é apenas o que o cliente afirmou ser a origem. Para decidir permissões, confie em client.

Um manipulador que dispara outro evento recebe de volta as suas cinco variáveis assim que o disparo aninhado retorna, então o código depois dele continua vendo o próprio evento.

Propagação

Um manipulador não escuta um evento no mundo inteiro: ele escuta um ponto da árvore de elementos. O manipulador registrado em attachedTo roda quando:

• attachedTo é o próprio source;
• source é descendente de attachedTo;
• attachedTo é o elemento root — nesse caso ele pega todos os eventos;
• attachedTo é descendente de source — o evento também desce pela árvore. No servidor, todo evento desce. No cliente, descem os eventos disparados com triggerEvent ou enviados pelo servidor, e também a maioria dos internos; os ganchos de cada frame, os eventos de entrada e mais alguns só sobem.

Os manipuladores rodam nessa ordem — os do source, depois os dos ancestrais, do mais próximo ao mais distante, depois os dos descendentes — e, no mesmo ponto da árvore, pela prioridade passada ao addEventHandler. Um manipulador adicionado com propagar igual a false só roda no primeiro caso.

Por isso addEventHandler("onPlayerJoin", root, ...) funciona para qualquer jogador, e anexar ao resourceRoot limita o manipulador aos elementos criados pelo seu resource.

addEvent Cria um evento novo, para que ele possa ser disparado com triggerEvent.

addEventHandler Registra uma função para rodar quando um evento dispara.

removeEventHandler Desfaz um addEventHandler.

getEventHandlers Lista os manipuladores que o seu resource anexou a um elemento.

triggerEvent Dispara um evento no lado que o chama.

cancelEvent Cancela o evento em execução.

wasEventCancelled Diz se um evento foi cancelado — o que está rodando, no servidor; o último que terminou, no cliente.

getCancelReason Devolve o motivo passado ao cancelEvent.