Eventos do servidor

Eventos são a forma de reagir ao que acontece no servidor: um jogador entra, um veículo explode, alguém pega um pickup. Você registra uma função e o servidor a chama quando aquilo acontece.

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

Todos os manipuladores registrados por um resource são removidos quando ele para.

addEventHandler

Registra uma função para ser chamada quando o evento disparar.

bool addEventHandler ( string nomeDoEvento, element elemento, function manipulador [, bool propagar = true, string prioridade = "normal" ] )

Parâmetros

Nome	Tipo	Descrição
nomeDoEvento	string	Nome do evento.
elemento	element	Elemento ao qual o manipulador fica preso. Veja Propagação.
manipulador	function	Função a chamar. Recebe os parâmetros do evento como argumentos.
propagar	bool	false faz o manipulador rodar só quando elemento é o próprio source. O padrão é true.
prioridade	string	"low", "normal" (o padrão) ou "high", opcionalmente com um modificador como "high+5". Decide a ordem entre manipuladores no mesmo ponto da árvore.

Retorno — true se o manipulador foi registrado, false caso contrário.

Um erro dentro do manipulador não derruba o servidor nem impede os outros manipuladores de rodar: ele é registrado no console com o nome do resource e do evento.

removeEventHandler

Desfaz um addEventHandler.

bool removeEventHandler ( string nomeDoEvento, element elemento, function manipulador )

O nome, o elemento e a função precisam ser exatamente os mesmos usados no registro — por isso guarde a função em uma variável se pretende removê-la depois.

local function aoEntrar()
    outputDebugString(getPlayerName(source) .. " entrou")
end

addEventHandler("onPlayerJoin", root, aoEntrar)
removeEventHandler("onPlayerJoin", root, aoEntrar)

Retorno — true se o manipulador existia e foi removido, false caso contrário.

getEventHandlers

Lista os manipuladores presos diretamente a um elemento.

table getEventHandlers ( string nomeDoEvento, element elemento )

Só aparecem os manipuladores registrados pelo seu próprio resource — os de outros resources ficam invisíveis. Um elemento sem manipuladores devolve uma tabela vazia; um argumento inválido devolve false.

for _, fn in ipairs(getEventHandlers("onPlayerJoin", root)) do
    removeEventHandler("onPlayerJoin", root, fn)
end

Globais do manipulador

Enquanto um manipulador está executando, cinco globais ficam disponíveis:

Global	Conteúdo
source	O elemento que originou o evento — o mesmo descrito na linha Source de cada evento abaixo.
client	O jogador que enviou o evento, quando ele veio do cliente. É nil em eventos disparados pelo próprio servidor.
eventName	O nome do evento em execução, como texto.
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.

Cuidado

Elas só existem durante a execução do manipulador. Assim que ele retorna, voltam ao que eram. Se você precisar de alguma depois — dentro de um setTimer, por exemplo — copie para uma variável local antes.

Cada manipulador recebe o próprio conjunto de valores e tem eles restaurados ao retornar, então um manipulador que dispara um evento aninhado continua vendo o seu próprio source na linha seguinte à chamada aninhada.

addEventHandler("onVehicleExplode", root, function(comExplosao)
    local veiculo = source                 -- cópia local: sobrevive ao timer
    outputDebugString(eventName .. " em " .. getVehicleName(veiculo))

    setTimer(function()
        if isElement(veiculo) then respawnVehicle(veiculo) end
    end, 5000, 1)
end)

Os parâmetros do evento não são globais: eles chegam como argumentos normais da função, na ordem descrita na referência abaixo.

Propagação

O elemento passado ao addEventHandler não precisa ser exatamente o source do evento. O manipulador roda quando qualquer uma destas condições é verdadeira:

• o elemento é o próprio source;
• o source é descendente do elemento, em qualquer profundidade;
• o elemento é a raiz (root);
• o elemento é descendente do source — os eventos descem pela árvore, além de subir.

Ou seja: prender à raiz pega tudo, prender à raiz do seu resource pega tudo o que o seu resource criou, e prender a um elemento específico pega ele e os filhos dele — além de qualquer evento disparado num ancestral dele, como um triggerEvent no root.

Os manipuladores rodam nessa ordem: os do source, depois os dos ancestrais, do mais próximo para cima, depois os dos descendentes. No mesmo ponto da árvore, quem decide é a prioridade. Um manipulador registrado com propagar igual a false só roda quando está preso ao próprio source.

local garagem = createElement("garagem")
local carro = createVehicle(411, 0, 0, 5)
setElementParent(carro, garagem)

-- roda para qualquer veículo do servidor
addEventHandler("onVehicleExplode", root, function() end)

-- roda só para os veículos dentro da "garagem"
addEventHandler("onVehicleExplode", garagem, function() end)

-- roda só para este carro
addEventHandler("onVehicleExplode", carro, function() end)

Quando um evento é disparado sem elemento de origem, apenas os manipuladores presos à raiz são executados.

Nota

Como os eventos também descem, um manipulador preso a um filho vê, sim, um evento cujo source é o pai. Confira o source dentro do manipulador, ou registre-o com propagar igual a false, quando quiser só os eventos do próprio elemento.

Eventos personalizados

Além dos eventos do servidor, você pode criar os seus.

addEvent

Registra um nome de evento.

bool addEvent ( string nomeDoEvento [, bool permitirRemoto = false ] )

Nome	Tipo	Padrão	Descrição
nomeDoEvento	string	—	Nome do evento.
permitirRemoto	bool	false	Se true, scripts do cliente podem disparar este evento no servidor.

Cuidado

Só use permitirRemoto = true quando o cliente realmente precisar chamar aquele evento — e trate os argumentos como não confiáveis. Quem manda o evento escolhe o source e todos os parâmetros; use client para saber de qual jogador ele veio de verdade.

triggerEvent

Dispara um evento no servidor, agora, no mesmo tick.

bool triggerEvent ( string nomeDoEvento, element origem [, ... ] )

Os valores extras viram os argumentos do manipulador.

Retorno — false se algum manipulador cancelou o evento, true caso contrário (inclusive quando ninguém está escutando).

addEvent("onCompraDeArma")

addEventHandler("onCompraDeArma", root, function(arma, preco)
    if getElementData(source, "dinheiro") < preco then
        cancelEvent(true, "saldo insuficiente")
    end
end)

addEventHandler("onCompraDeArma", root, function()
    if wasEventCancelled() then
        outputDebugString("compra recusada: " .. getCancelReason())
    end
end, true, "low")   -- roda depois do manipulador acima

if triggerEvent("onCompraDeArma", jogador, 31, 5000) then
    giveWeapon(jogador, 31, 200)
end

triggerClientEvent

Dispara um evento nos clientes.

bool triggerClientEvent ( element/table destinos, string nomeDoEvento, element origem [, ... ] )

Nome	Tipo	Descrição
destinos	element ou table	Para quem enviar. Um jogador atinge só ele; qualquer outro elemento atinge todos os jogadores abaixo dele na árvore — passar root atinge o servidor inteiro. Uma tabela de elementos também é aceita.
nomeDoEvento	string	Nome do evento no cliente.
origem	element	Elemento que vira o source do lado do cliente.
...	any	Argumentos repassados ao manipulador do cliente.

Do lado do cliente, o evento só é entregue se tiver sido registrado com addEvent(nome, true). Sem isso, a mensagem é descartada silenciosamente.

triggerClientEvent(root, "onPlacarAtualizado", root, "Gabriel", 12)

Para uma carga grande, triggerLatentClientEvent manda o mesmo evento por uma fila com banda limitada, em vez de tudo de uma vez.

Cancelando eventos

cancelEvent

Marca o evento em execução como cancelado.

bool cancelEvent ( [ bool cancelar = true, string motivo = "" ] )

Sempre devolve true. Chamar cancelEvent(false) não faz nada — em particular, não desfaz um cancelamento feito por outro manipulador.

wasEventCancelled

bool wasEventCancelled ( )

Devolve true se o evento em execução já foi cancelado por algum manipulador.

getCancelReason

string getCancelReason ( )

Devolve o motivo passado ao cancelEvent para o evento em execução, ou uma string vazia se não houve motivo. Depois que triggerEvent retorna, o motivo some — leia-o num manipulador posterior, como no exemplo acima.

Nota

Cancelar só muda alguma coisa se o evento for cancelável — a referência abaixo diz quais são. Nos demais, o cancelamento é registrado mas o servidor ignora.

Cada disparo tem o próprio estado de cancelamento: se um manipulador chamar triggerEvent para outro evento, o cancelamento do evento interno não afeta o externo.

Referência de eventos

O servidor dispara 86 eventos, agrupados por área:

Jogadores

onPlayerConnect Disparado quando um cliente termina de se conectar, antes de ele entrar no servidor.

onPlayerJoin Disparado quando um jogador termina de conectar e entra no servidor.

onPlayerQuit Disparado quando um jogador sai do servidor.

onPlayerSpawn Disparado depois que spawnPlayer coloca um jogador no mundo.

onPlayerChangeNick Disparado quando o apelido de um jogador vai mudar.

onPlayerVehicleEnter Disparado quando um jogador passa a ocupar um veículo.

onPlayerVehicleExit Disparado quando um jogador deixa de ocupar um veículo.

onPlayerWeaponReload Disparado quando reloadPedWeapon é chamado para um jogador, antes da recarga acontecer.

onPlayerDetonateSatchels Disparado quando um jogador vai detonar as próprias cargas explosivas — tanto pelo comando do jogo quanto por detonateSatchels.

onPlayerTeleport Disparado quando a posição sincronizada de um jogador dá um salto maior que 20 unidades de uma leitura para a outra.

onPlayerTarget Disparado quando o jogador passa a mirar em outro elemento — ou deixa de mirar em qualquer coisa.

onPlayerContact Disparado quando muda o elemento em que o jogador está encostado (o chão de um veículo, um objeto, etc.).

onPlayerClick Disparado quando um jogador clica com o cursor visível.

onPlayerScreenShot Disparado quando chega o resultado de um takePlayerScreenShot.

onPlayerChangesWorldSpecialProperty Disparado quando um script de cliente liga ou desliga uma propriedade especial do mundo com setWorldSpecialPropertyEnabled.

Peds

onPedVehicleEnter Disparado quando um ped é colocado em um veículo por warpPedIntoVehicle.

onPedVehicleExit Disparado quando um ped é tirado de um veículo — por removePedFromVehicle, por um warpPedIntoVehicle tomando o assento dele, ou quando um jogador o arranca num roubo.

onPedWeaponReload Disparado quando reloadPedWeapon é chamado para um ped que não é jogador, antes da recarga acontecer.

Combate

Os eventos de combate nascem do relato do cliente. O servidor valida cada número antes de disparar o evento — dano fora da faixa de 0 a 200, atacante em outra dimensão ou interior, morte relatada duas vezes e faca a mais de 5 unidades de distância são descartados sem disparar nada.

onPlayerDamage Disparado quando um jogador leva dano.

onPedDamage Disparado quando um ped leva dano.

onPlayerWasted Disparado quando um jogador morre.

onPedWasted Disparado quando um ped morre.

onPlayerWeaponFire Disparado a cada tiro de um jogador.

onPlayerWeaponSwitch Disparado quando a arma na mão de um jogador muda.

onPedWeaponSwitch O mesmo de onPlayerWeaponSwitch para peds que não são jogadores.

onPlayerStealthKill Disparado quando um jogador relata um golpe furtivo de faca.

onPlayerProjectileCreation Disparado quando um jogador lança um projétil (foguete, granada, coquetel molotov).

onExplosion Disparado antes de o servidor distribuir uma explosão — tanto uma criada por createExplosion quanto uma relatada por um cliente.

Veículos

onVehicleStartEnter Disparado quando o servidor recebe a intenção de um jogador entrar em um veículo, antes de aprovar a entrada.

onVehicleStartExit Disparado quando o servidor recebe a intenção de um jogador sair de um veículo.

onVehicleEnter O par de onPlayerVehicleEnter e onPedVehicleEnter visto pelo lado do veículo.

onVehicleEnterFailed Dispara quando um jogador que já tinha sido liberado para entrar desiste no meio do caminho: o cliente avisa que a animação de entrada foi abortada, e o servidor libera o assento que tinha reservado.

onVehicleExit O par de onPlayerVehicleExit e onPedVehicleExit visto pelo lado do veículo.

onVehicleDamage Disparado sempre que a vida sincronizada de um veículo cai.

onVehicleExplode Disparado quando um veículo explode — seja no jogo, seja porque um script chamou blowVehicle.

onVehicleRespawn Disparado depois que um veículo volta para a posição de respawn com a vida cheia — seja por respawnVehicle, seja pelos temporizadores de toggleVehicleRespawn.

onTrailerAttach Disparado quando um reboque é preso a um veículo com attachTrailerToVehicle.

onTrailerDetach Disparado quando um reboque é solto com detachTrailerFromVehicle.

Objetos

onDynamicObjectRest Disparado quando um objeto em física dinâmica vem ao repouso — o cliente que pilotava a física dele avisa que o objeto parou, e o servidor grava a pose de repouso no objeto antes de o evento rodar.

Fratura

onObjectFracture Disparado quando um objeto armado com um perfil de fratura quebra sozinho — o dano desgastou a vida de fratura dele até 0. Quebrá-lo à mão com createObjectFracture não dispara este evento.

onFractureRest Disparado quando todos os fragmentos de uma fratura ficam em repouso ao mesmo tempo por um segundo inteiro. Dispara uma vez por fratura.

onFractureEnd Disparado quando uma fratura termina sozinha — o tempo de vida dela acabou. O elemento de fratura e seus fragmentos são destruídos logo depois que o evento retorna.

Elementos

onElementCreated Disparado assim que um elemento é criado, logo depois de o servidor avisar os clientes sobre ele.

onElementDestroy Disparado quando um elemento está sendo destruído.

onElementDataChange Disparado quando um dado de elemento é escrito ou removido.

onElementModelChange Disparado quando setElementModel muda o modelo de um elemento.

onElementDimensionChange Disparado quando a dimensão de um elemento muda de verdade.

onElementInteriorChange Disparado quando o interior de um elemento muda de verdade.

onElementClicked Disparado quando um jogador clica em cima de um elemento.

onElementAttach Disparado quando attachElements prende um elemento a outro.

onElementDetach Disparado quando detachElements solta um elemento.

onPlayerChangesProtectedData Disparado quando um cliente tenta escrever um dado de elemento que não tem permissão de escrever.

Formas de colisão

Cada entrada e cada saída disparam um par de eventos: um com a forma como source e outro com o elemento como source. A verificação roda para jogadores, peds, veículos e objetos.

Nota

A dimensão é informada, não filtrada: o evento dispara mesmo quando o elemento e a forma estão em dimensões diferentes. Use o parâmetro mesmaDimensao se você quiser ignorar esses casos.

onColShapeHit Disparado quando um elemento entra numa forma de colisão.

onColShapeLeave Disparado quando um elemento sai de uma forma de colisão.

onElementColShapeHit O mesmo momento de onColShapeHit, visto pelo lado do elemento.

onElementColShapeLeave O mesmo momento de onColShapeLeave, visto pelo lado do elemento.

Marcadores

Marcadores funcionam como as formas de colisão, com duas diferenças: o interior precisa bater (um elemento em outro interior conta como fora do marcador) e existe um par extra de eventos só para jogadores.

O formato depende do tipo do marcador: checkpoint e cylinder ignoram a altura, e todos os demais são esferas. O raio é o tamanho do marcador.

onMarkerHit Disparado quando um elemento entra num marcador.

onMarkerLeave Disparado quando um elemento sai de um marcador.

onPlayerMarkerHit O mesmo momento de onMarkerHit, visto pelo lado do jogador.

onPlayerMarkerLeave O mesmo momento de onMarkerLeave, visto pelo lado do jogador.

Pickups

Cada coleta dispara um par de eventos: um com o pickup como source e outro com o jogador como source. Os dois sempre disparam; cancelar qualquer um dos dois já é suficiente para bloquear o efeito.

Um pickup só é testado contra jogadores vivos, no mesmo interior e na mesma dimensão, dentro de um raio de 1 unidade.

onPickupHit Disparado quando um jogador entra na área de um pickup visível.

onPlayerPickupHit O mesmo momento de onPickupHit, visto pelo lado do jogador.

onPickupUse Disparado quando o pickup é realmente consumido, logo antes do efeito ser aplicado.

onPlayerPickupUse O mesmo momento de onPickupUse, visto pelo lado do jogador.

onPickupLeave Disparado quando um jogador sai da área de um pickup em que havia entrado.

onPlayerPickupLeave O mesmo momento de onPickupLeave, visto pelo lado do jogador.

onPickupSpawn Disparado quando um pickup reaparece depois do intervalo de respawn.

Resources

onResourceStart Disparado depois que um resource carregou, rodou todos os scripts de servidor com sucesso e entrou no estado running, mas antes de o início ser anunciado aos cl

onResourceStop Disparado quando um resource está sendo parado, enquanto os scripts dele ainda estão vivos.

onResourcePreStart Disparado logo antes de um resource iniciar, antes de os scripts dele rodarem.

onResourceStateChange Disparado quando um resource em execução muda de estado.

onResourceLoadStateChange Disparado quando um resource entra, muda ou sai da lista de resources — o que o refresh faz.

onPlayerResourceStart Disparado uma vez por jogador, por resource, quando aquele jogador termina de receber o lado cliente de um resource.

Comandos e moderação

onPlayerCommand Disparado antes de qualquer manipulador de comando do servidor quando há um jogador como origem.

onConsole Disparado depois que uma linha passa pelo sistema de comandos Lua do servidor, com o comando e os argumentos.

onPlayerMute Disparado quando um jogador vai ser silenciado por setPlayerMuted.

onPlayerUnmute Disparado quando um jogador vai deixar de ser silenciado por setPlayerMuted.

onPlayerTriggerEventThreshold Disparado quando um jogador passa do limite de eventos enviados ao servidor: mais de 100 envios dentro de uma janela de um segundo.

onPlayerTriggerInvalidEvent Disparado quando um jogador tenta disparar no servidor um evento que não existe, ou que existe mas não foi liberado para o cliente.

onPlayerAnticheatViolation Disparado toda vez que o anticheat registra uma violação para um jogador — inclusive as ocorrências que ainda não atingiram o limite da política.

Voz

Estes eventos só existem quando o chat de voz está ligado na configuração do servidor.

onPlayerVoiceStart Disparado quando um jogador começa a falar.

onPlayerVoiceStop Disparado quando um jogador para de falar.

onPlayerVoiceChannelStart Disparado quando um jogador começa a enviar áudio para um canal de voz.

onPlayerVoiceChannelStop Disparado quando um jogador para de enviar áudio para um canal de voz.

Servidor

onDebugMessage Disparado para toda mensagem que a camada de script manda para a saída de debug: outputDebugString, erros de execução de script e as reclamações de argumento in

onShutdown Disparado quando o servidor está caindo, antes de os resources serem parados.