Eventos

Eventos são o principal meio de reagir ao que acontece no jogo. Você registra uma função e o MTAX a chama quando algo ocorre.

addEventHandler("onPlayerJoin", root, function()
    outputDebugString(getPlayerName(source) .. " entrou")
end)

Onde cada evento é disparado

Assim como as funções, os eventos são separados por lado — e um evento não atravessa a fronteira sozinho.

Eventos do servidor (86) Disparados no servidor: entrada de jogadores, veículos, pickups e resources.

Eventos de cliente (105) 105 eventos do bus na máquina do jogador. A página também documenta o callback onClientSVGUpdate à parte.

Um manipulador registrado no servidor nunca recebe um evento de cliente, e vice-versa. Para mandar informação de um lado ao outro você usa triggerServerEvent e triggerClientEvent, que estão documentados nas respectivas páginas.

Cada evento tem a sua própria página, em …/events/<lado>/<onNomeDoEvento>/, dizendo onde ele dispara, se cancelEvent tem efeito sobre ele, qual é o source, os parâmetros por posição e um exemplo. As duas páginas acima são o índice de cada lado: explicam como os manipuladores funcionam e listam os eventos por área.

Globais dentro de um manipulador

Enquanto um manipulador roda, algumas variáveis globais ficam preenchidas:

Global	Onde existe	Conteúdo
source	ambos	O elemento que originou o evento.
eventName	ambos	O nome do evento em execução.
client	servidor	O jogador que enviou o evento, quando ele veio do cliente.
sourceResource	ambos	O resource cujo script disparou o evento; nil quando quem disparou foi a engine ou a rede.
sourceResourceRoot	ambos	O elemento raiz desse resource, pela mesma regra.

Fora do manipulador, todas voltam a ser nil.

Propagação

O segundo argumento de addEventHandler define em qual parte da árvore você quer escutar:

addEventHandler("onPlayerJoin", root, handler)          -- todos os jogadores
addEventHandler("onVehicleExplode", meuVeiculo, handler) -- só este veículo

Um manipulador é chamado quando o elemento em que ele foi registrado é o próprio source, é um ancestral do source, ou é a raiz. Registrar em root alcança tudo. Os eventos também descem: um manipulador num descendente do source roda também. No servidor isso vale para todo evento; no cliente, vale para os eventos disparados por scripts ou enviados pelo servidor e para a maioria dos internos.

Cuidado

Alguns eventos do cliente têm root como source e não descem — entre eles os ganchos de cada frame e os eventos de entrada. Para esses, registrar em resourceRoot nunca dispara, porque resourceRoot está abaixo de root. A página de eventos do cliente lista quais são.

Eventos personalizados

Você também pode criar os seus:

addEvent("onMeuEventoPersonalizado", false)

addEventHandler("onMeuEventoPersonalizado", root, function(quantia)
    outputDebugString("recebi " .. quantia)
end)

triggerEvent("onMeuEventoPersonalizado", root, 100)

O segundo argumento de addEvent controla se o evento pode ser disparado remotamente pelo outro lado. Mantenha false a menos que precise — e, quando precisar, valide tudo o que chegar.