Eventos de cliente

Os eventos desta página disparam só no cliente, dentro do jogo de um jogador. O próprio evento e seus handlers nunca atravessam essa fronteira. O protocolo pode relatar separadamente ao servidor a ação correspondente — como dano ou uma explosão — e também encaminha automaticamente as linhas digitadas no F8 depois dos manipuladores locais. Para enviar dados próprios, use triggerServerEvent.

Você registra um manipulador exatamente como faz no servidor:

addEventHandler("onClientVehicleExplode", root, function()
    outputDebugString(getVehicleName(source) .. " explodiu")
end)

addEventHandler, removeEventHandler, getEventHandlers, eventos personalizados e as regras de propagação estão descritos na página de Eventos e nas funções de eventos — funcionam do mesmo jeito aqui, e a página de cada função aponta onde o cliente difere. Esta página cobre só a lista de eventos que o cliente dispara sozinho.

São 106 nomes no total: 105 eventos que você pega com addEventHandler e o onClientSVGUpdate, que é o único que não passa pelo sistema de eventos — ele só chega à função que você registra.

Todos os manipuladores registrados por um resource somem quando ele para. Um manipulador preso diretamente a um elemento também é removido automaticamente logo depois do onClientElementDestroy daquele elemento.

Globais do manipulador

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

Global	Conteúdo
source	O elemento que originou o evento — o mesmo descrito na linha Source de cada evento abaixo.
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 o servidor.
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.

Não existe client no cliente: aqui não há “de qual jogador veio”, porque tudo acontece na máquina de um jogador só.

Globais do cliente

Três elementos ficam sempre à mão nos scripts de cliente e aparecem o tempo todo nos manipuladores:

Global	Conteúdo
localPlayer	O jogador desta máquina. É a resposta para “sou eu?” dentro de um manipulador.
root	A raiz da árvore de elementos. Prender um manipulador aqui pega o evento venha ele de onde vier.
resourceRoot	A raiz do seu resource. Serve para filtrar onClientResourceStart e onClientResourceStop para o seu próprio resource.

O uso mais comum de localPlayer é separar o que aconteceu com você do que aconteceu com os outros:

addEventHandler("onClientVehicleEnter", root, function(ped, assento)
    if ped == localPlayer and assento == 0 then
        outputDebugString("assumi a direção de " .. getVehicleName(source))
    end
end)

Onde prender o manipulador

Dezesseis eventos desta página têm a raiz como source: os quatro ganchos de quadro (onClientPedsProcessed, onClientPreRender, onClientRender, onClientHUDRender), os seis de entrada (onClientKey, onClientCharacter, onClientClick, onClientDoubleClick, onClientCursorMove, onClientPaste), os cinco de janela e log (onClientMTAXFocusChange, onClientPauseMenuOpen, onClientMinimize, onClientRestore, onClientDebugMessage) e o onClientPlayerReady.

No cliente os eventos normalmente descem pela árvore, além de subir, mas os ganchos de quadro, os eventos de entrada e os três de janela (foco, minimizar, restaurar) só sobem — então só chegam a manipuladores presos a root. Prender um deles a resourceRoot ou a um elemento qualquer não dá erro, mas o manipulador nunca roda. onClientPauseMenuOpen, onClientDebugMessage e onClientPlayerReady descem, então um manipulador em resourceRoot também os recebe.

O onClientExplosion é o caso híbrido: normalmente o source é o elemento responsável pela explosão, mas quando não há elemento nenhum por trás dela o evento cai na raiz — e nesse caso só chega a manipuladores presos a root.

Cancelamento

cancelEvent, wasEventCancelled e getCancelReason existem no cliente e funcionam nos eventos que você dispara com triggerEvent.

Vinte e seis eventos desta página também respondem ao cancelamento — o cliente olha para o resultado e desfaz, bloqueia ou reverte o que ia acontecer:

Evento	O que o cancelamento faz
onClientPlayerDamage · onClientPedDamage	Barra o golpe no ponto de aplicação e preserva vida e colete.
onClientPlayerChoke	Interrompe o engasgo e ignora novos engasgos por um segundo e meio.
onClientPlayerHeliKilled · onClientPedHeliKilled	A hélice não mata.
onClientPlayerHitByWaterCannon · onClientPedHitByWaterCannon	O jato para de empurrar por meio segundo.
onClientExplosion	A explosão não acontece.
onClientWeaponFire	O tiro não deixa impacto.
onClientPlayerWeaponSwitch	A arma volta para a que estava na mão.
onClientPlayerStealthKill	O golpe pelas costas não sai.
onClientPlayerRadioSwitch	A estação continua a mesma.
onClientElementModelChange	O modelo antigo é mantido — só quando a troca veio de setElementModel.
onClientVehicleStartEnter	A tarefa de entrar do jogador local não começa; para um ped criado por este cliente, setPedEnterVehicle devolve false.
onClientVehicleStartExit	Só para um ped criado por este cliente: setPedExitVehicle devolve false.
onClientVehicleEnter	Só para um ped criado por este cliente: ele é tirado de volta do veículo.
onClientVehicleDamage	A vida anterior do veículo é restaurada.
onClientWorldSound	O jogo nunca toca aquele som.
onClientPauseMenuOpen	O menu principal não abre.
onClientPlayerWeaponReload · onClientPedWeaponReload	A arma não é recarregada nesta máquina.
onClientElementAttach · onClientElementDetach	O anexo ou a separação não é aplicado — um attachElements/detachElements local devolve false, e um anunciado pelo servidor é ignorado só nesta máquina.
onClientKey	A tecla não chega a nenhum bind de bindKey. O jogo em si ainda a recebe.
onClientDebugMessage	A mensagem não aparece no console de debug.
onClientPlayerVoiceStart	O microfone do jogador local continua desligado; a fala de outro jogador é silenciada nesta máquina.

Cuidado

Os demais eventos não são canceláveis. São avisos do que já aconteceu: o cancelamento é registrado, mas o cliente não olha para ele. Se você precisa impedir alguma coisa que não está na tabela acima, faça isso no servidor.

Referência de eventos

---

Quadro

Quatro eventos disparam em todo quadro, sempre nesta ordem:

Ordem	Evento	Para que serve
1	onClientPedsProcessed	Os personagens do mundo já foram atualizados. É o ponto mais cedo do quadro em que dá para ler posições e vida de todo mundo.
2	onClientPreRender	Recebe o tempo decorrido desde o quadro anterior. É onde entra o que precisa de um passo de tempo: interpolação, movimento de câmera, contadores.
3	onClientRender	O gancho de desenho. Tudo que você desenha aqui aparece sobre o mundo.
4	onClientHUDRender	O último do quadro. O que você desenha aqui fica por cima do que foi desenhado no onClientRender.

Os quatro têm a raiz como source, nenhum é cancelável e as funções de desenho funcionam nos quatro. A diferença prática é só ordem: quem desenha depois cobre quem desenhou antes.

Cuidado

Tudo que você põe nestes quatro roda de 30 a 300 vezes por segundo, dependendo da máquina do jogador. Laços grandes, buscas em tabelas inteiras e criação de objetos dentro deles aparecem direto no FPS. Guarde resultados em variáveis e recalcule só quando algo muda.

onClientPedsProcessed Disparado uma vez por quadro, depois que todos os personagens do mundo foram atualizados e antes de qualquer coisa ser desenhada.

onClientPreRender Disparado uma vez por quadro, logo antes do onClientRender.

onClientRender Disparado uma vez por quadro, no meio do trio de desenho.

onClientHUDRender Disparado uma vez por quadro, depois do onClientRender.

Entrada

Nota

Enquanto o menu do cliente ou o console de debug estão abertos, eles ficam com o teclado e o mouse. Nesse intervalo, nenhum dos eventos de entrada dispara.

onClientKey Disparado quando uma tecla é pressionada ou solta.

onClientCharacter Disparado quando o jogador digita um caractere.

onClientClick Disparado quando um botão do mouse é pressionado ou solto com o cursor visível.

onClientDoubleClick Disparado quando um clique acontece logo depois de outro, no mesmo lugar.

onClientCursorMove Disparado quando o cursor do mouse se move.

onClientPaste Disparado quando o jogador aperta Ctrl + V.

Janela e console

onClientMTAXFocusChange Disparado quando a janela do jogo ganha ou perde o foco.

onClientPauseMenuOpen Disparado quando o jogador está prestes a abrir o menu principal do MTAX — com Esc, ou por qualquer outro caminho que a interface ofereça.

onClientMinimize Disparado quando a janela do jogo é minimizada.

onClientRestore Disparado quando a janela do jogo volta de minimizada.

onClientConsole Disparado quando uma linha é digitada no console do cliente, depois de os manipuladores de comando locais rodarem e imediatamente antes de a linha ser encaminha

onClientDebugMessage Disparado quando uma mensagem de script vai para o log.

Jogadores e peds

onClientPlayerReady Disparado quando o jogador local termina de carregar, o mundo está pronto para ser usado e todos os scripts e assets de resources pedidos pelo servidor já foram

onClientPlayerJoin Disparado quando um jogador remoto passa a existir no mundo deste cliente.

onClientPlayerQuit Disparado quando um jogador deixa de existir no mundo deste cliente.

onClientPlayerSpawn Disparado quando o jogador local nasce, e a cada renascimento depois disso.

onClientPlayerWasted Disparado quando um jogador morre.

onClientPedWasted Disparado quando um ped que não é jogador morre.

onClientPlayerChangeNick Disparado quando o nome de um jogador muda.

Combate

onClientPlayerDamage Disparado quando um jogador leva dano.

onClientPedDamage O mesmo momento do onClientPlayerDamage, quando quem levou o dano é um ped em vez de um jogador.

onClientPlayerWeaponFire Disparado quando um jogador dá um tiro.

onClientPedWeaponFire O mesmo momento do onClientPlayerWeaponFire, quando quem atirou é um ped.

onClientWeaponFire Disparado quando uma arma criada por script dá um tiro.

onClientPlayerWeaponSwitch Disparado quando o jogador local troca de arma.

onClientPlayerWeaponReload Disparado quando o servidor recarrega a arma de um jogador com reloadPedWeapon, logo antes de a recarga acontecer nesta máquina.

onClientPedWeaponReload O mesmo momento de onClientPlayerWeaponReload, quando a arma é de um ped.

onClientPlayerTarget Disparado quando o alvo da mira do jogador local muda.

onClientPlayerStealthKill Disparado quando o jogador local está prestes a dar um golpe de faca pelas costas.

onClientPlayerChoke Disparado quando o jogador local começa a engasgar com gás ou spray.

onClientPlayerHeliKilled Disparado quando as hélices de um helicóptero estão prestes a matar um jogador.

onClientPedHeliKilled O mesmo momento do onClientPlayerHeliKilled, quando a vítima é um ped.

onClientPlayerHitByWaterCannon Disparado quando o jato de um canhão de água empurra um jogador.

onClientPedHitByWaterCannon O mesmo momento do onClientPlayerHitByWaterCannon, quando quem é empurrado é um ped.

onClientExplosion Disparado quando uma explosão vai acontecer no mundo do jogador.

onClientProjectileCreation Disparado quando um projétil aparece no mundo — granada arremessada, foguete, bomba colada.

Movimento e manobras

onClientPedStep Disparado a cada passo que um personagem dá.

onClientPlayerStuntStart Disparado quando o jogador local começa uma manobra.

onClientPlayerStuntFinish Disparado quando o jogador local termina uma manobra.

Veículos

onClientVehicleStartEnter Disparado quando o jogador local tenta entrar em um veículo, antes de a animação começar e de o pedido de aprovação ser enviado ao servidor.

onClientVehicleStartExit Disparado quando o jogador local tenta sair de um veículo, antes de a tarefa de saída começar.

onClientVehicleEnter O mesmo momento de onClientPlayerVehicleEnter e onClientPedVehicleEnter, visto pelo lado do veículo.

onClientVehicleEnterFailed Dispara na máquina do jogador local quando o servidor recusa uma tentativa de entrar em um veículo.

onClientVehicleExit O mesmo momento de onClientPlayerVehicleExit e onClientPedVehicleExit, visto pelo lado do veículo.

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

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

onClientPedVehicleEnter Disparado quando um ped que não é jogador é colocado em um veículo pelo servidor.

onClientPedVehicleExit Disparado quando um ped que não é jogador é tirado de um veículo pelo servidor.

onClientVehicleDamage Disparado quando um veículo está prestes a levar dano.

onClientVehicleCollision Disparado quando um veículo bate em alguma coisa.

onClientVehicleWeaponHit Disparado quando a arma de um veículo acerta alguma coisa.

onClientVehicleExplode Disparado quando um veículo explode.

onClientVehicleRespawn Disparado quando um veículo volta para a posição de respawn.

onClientVehicleNitroStateChange Disparado quando o nitro de um veículo é ativado ou desativado.

onClientTrailerAttach Disparado quando um reboque é engatado a um veículo.

onClientTrailerDetach Disparado quando um reboque é solto.

Objetos

onClientObjectMoveStart Disparado quando um objeto começa a se mover.

onClientObjectMoveStop Disparado quando um objeto para de se mover — porque chegou ao destino ou porque o movimento foi interrompido.

onClientObjectBreak Disparado quando um objeto quebrável se parte.

onClientObjectDamage Disparado quando a vida de um objeto cai.

onClientObjectFracture Disparado quando uma fratura fica visível pela primeira vez nesta máquina — o primeiro fragmento dela resolveu a malha cortada. Vale tanto para uma fratura replicada pelo servidor quanto para um efeito de quebra criado com createObjectBreakEffect.

Elementos

onClientElementCreated Disparado quando um elemento criado no servidor passa a existir nesta máquina.

onClientElementDataChange Disparado quando o servidor muda um dado de um elemento.

onClientElementStreamIn Disparado quando um elemento criado pelo servidor entra na distância de streaming e passa a existir no mundo do jogador.

onClientElementStreamOut Disparado quando um elemento criado pelo servidor sai da distância de streaming e deixa de existir no mundo do jogador.

onClientElementDestroy Disparado quando um elemento está prestes a deixar de existir.

onClientElementModelChange Disparado quando setElementModel no cliente muda o modelo de um objeto, veículo, jogador ou ped.

onClientElementInteriorChange Disparado quando o interior de um elemento muda.

onClientElementDimensionChange Disparado quando a dimensão de um elemento muda.

onClientElementAttach Disparado nesta máquina quando um elemento é preso a outro.

onClientElementDetach Disparado nesta máquina quando um elemento é solto de outro.

onClientSVGUpdate O nome que aparece em eventName enquanto roda o callback registrado com svgSetUpdateCallback.

Áreas e marcadores

Áreas de colisão e marcadores são testados uma vez por quadro contra jogadores, peds, veículos e objetos. Os eventos disparam na transição — entrou ou saiu —, nunca continuamente enquanto o elemento fica dentro.

Cada toque em uma área gera dois eventos: um com a área como source e outro com o elemento como source. Marcadores geram um, mais o onClientPlayerMarkerHit na entrada e o onClientPlayerMarkerLeave na saída quando o elemento é um jogador.

Nota

Nenhum destes eventos é cancelável, e o parâmetro mesmaDimensao é informação, não filtro: uma área dispara mesmo quando o elemento está em outra dimensão, e cabe a você decidir se isso conta.

Marcadores são a exceção parcial: o interior precisa bater para o marcador considerar o elemento dentro. Dimensão diferente ainda dispara; interior diferente não.

onClientColShapeHit Disparado quando um elemento entra em uma área de colisão.

onClientColShapeLeave Disparado quando um elemento sai de uma área de colisão.

onClientElementColShapeHit O mesmo momento do onClientColShapeHit, visto pelo lado do elemento.

onClientElementColShapeLeave O mesmo momento do onClientColShapeLeave, visto pelo lado do elemento.

onClientMarkerHit Disparado quando um elemento entra em um marcador.

onClientMarkerLeave Disparado quando um elemento sai de um marcador.

onClientPlayerMarkerHit O mesmo momento de onClientMarkerHit, visto do lado do jogador.

onClientPlayerMarkerLeave O mesmo momento de onClientMarkerLeave, visto do lado do jogador.

Pickups

Cada entrada em um pickup dispara dois eventos, nesta ordem: primeiro onClientPickupHit, depois onClientPlayerPickupHit. A saída faz o mesmo com o par de saída.

Nota

Os quatro são apenas avisos. O efeito do pickup é decidido pelo servidor — nada que você faça aqui impede ou muda a coleta. E só o jogador local dispara estes eventos: pickups não reagem a outros jogadores no seu cliente.

onClientPickupHit Disparado quando o jogador local encosta em um pickup visível.

onClientPickupLeave Disparado quando o jogador local sai de cima de um pickup.

onClientPlayerPickupHit O mesmo momento de onClientPickupHit, visto pelo lado do jogador.

onClientPlayerPickupLeave O mesmo momento de onClientPickupLeave, visto pelo lado do jogador.

Resources

onClientResourceStart Disparado depois que um resource terminou de rodar todos os seus scripts de cliente.

onClientResourceStop Disparado quando um resource está parando, enquanto os scripts de cliente dele ainda estão vivos.

Downloads

Estes avisam sobre o download de assets que acontece antes de um resource iniciar. São a base para você montar a sua própria tela de download, no lugar da caixa de transferência embutida.

onClientResourceFileDownload Disparado a cada mudança de estado de um arquivo sendo baixado para um resource.

onClientFileDownloadComplete Disparado quando um arquivo termina de baixar, tendo dado certo ou não.

onClientTransferBoxVisibilityChange Disparado quando a caixa de transferência aparece ou some.

onClientTransferBoxProgressChange Disparado conforme o download avança.

Voz e rádio

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

onClientPlayerVoiceStart Disparado quando um jogador começa a falar.

onClientPlayerVoiceStop Disparado quando um jogador para de falar.

onClientPlayerVoicePause Disparado quando você silencia a voz de um jogador com setSoundPaused.

onClientPlayerVoiceResumed Disparado quando você volta a ouvir a voz de um jogador silenciado.

onClientPlayerRadioSwitch Disparado quando a estação de rádio do jogador local muda.

onClientSoundStarted Dispara quando um elemento de som começa a tocar.

onClientSoundStopped Dispara quando um elemento de som para.

onClientSoundStream Dispara quando um stream de internet aberto com playSound termina de conectar — tendo dado certo ou não.

onClientSoundFinishedDownload Dispara quando um stream termina de ser baixado.

onClientSoundChangedMeta Dispara quando um stream shoutcast anuncia uma faixa nova.

onClientSoundBeat Dispara a cada batida detectada em um som.

onClientWorldSound Dispara quando o jogo — e não um script — está prestes a tocar um som dele: um tiro, um passo, uma porta, um motor.