Eventos dos Scripts FiveM: Guia Completo de Uso Lua

Referência completa dos eventos cliente e servidor dos scripts FiveM, com exemplos de AddEventHandler, TriggerEvent e TriggerServerEvent prontos para uso.

Os eventos permitem que seu código reaja a ações que ocorrem nos scripts. Você pode escutar eventos com AddEventHandler (no cliente ou no servidor) e disparar eventos entre as camadas com TriggerEvent ou TriggerServerEvent. Esta página cobre todos os padrões de uso com exemplos práticos.

Como Escutar Eventos com AddEventHandler

Use AddEventHandler para reagir a eventos disparados pelo script ou por outros recursos:

-- No cliente: escutar um evento de cliente
AddEventHandler('meuScript:onJobChange', function(jobName, jobLabel, grade, gradeLabel)
    print('Novo emprego: ' .. jobLabel .. ' - ' .. gradeLabel)
end)

-- No servidor: escutar um evento de servidor
AddEventHandler('meuScript:itemUsed', function(itemName, quantity)
    local source = source  -- ID do jogador que disparou o evento
    print('Jogador ' .. source .. ' usou ' .. quantity .. 'x ' .. itemName)
end)

Como Disparar Eventos com TriggerEvent

Use TriggerEvent para disparar um evento local (na mesma camada — cliente para cliente ou servidor para servidor):

-- No cliente: disparar evento local para outros handlers no mesmo cliente
TriggerEvent('meuScript:onMoneyChange', 'cash', 500, 'salario')

-- No servidor: disparar evento local no servidor
TriggerEvent('meuScript:onPayday', 1000, 'Polícia')

Como Disparar Eventos com TriggerServerEvent

Use TriggerServerEvent no cliente para enviar dados ao servidor. O servidor recebe o evento e tem acesso ao source (ID do jogador que disparou):

-- No cliente: enviar ação para o servidor
TriggerServerEvent('meuScript:usarItem', 'water', 1)

-- No servidor: receber e processar o evento
AddEventHandler('meuScript:usarItem', function(itemName, quantity)
    local source = source  -- ID do jogador que disparou
    print('Jogador ' .. source .. ' quer usar ' .. quantity .. 'x ' .. itemName)

    -- Valide sempre no servidor antes de executar ações
    local temItem = exports['meu-inventario']:HasItem(source, itemName, quantity)
    if temItem then
        exports['meu-inventario']:RemoveItem(source, itemName, quantity)
        TriggerClientEvent('meuScript:itemConsumed', source, itemName)
    end
end)

Nunca confie em dados vindos do cliente sem validar no servidor. Sempre verifique permissões e inventários do lado do servidor antes de executar ações.

Como Disparar Eventos com TriggerClientEvent

Use TriggerClientEvent no servidor para enviar dados de volta a um jogador específico (ou a todos):

-- Enviar evento para um jogador específico
TriggerClientEvent('meuScript:showNotification', source, 'Você recebeu um item!')

-- Enviar evento para todos os jogadores conectados
TriggerClientEvent('meuScript:serverAnnounce', -1, 'Evento de servidor iniciado!')

-- No cliente: receber e exibir a notificação
AddEventHandler('meuScript:showNotification', function(mensagem)
    print('[Notificação] ' .. mensagem)
end)

Módulo: Jobs — Eventos

meuScript:onJobChange (Cliente)

Disparado quando o emprego do jogador é alterado.

AddEventHandler('meuScript:onJobChange', function(jobName, jobLabel, grade, gradeLabel)
    print('Novo emprego: ' .. jobLabel .. ' - ' .. gradeLabel)
end)

Parâmetros:

• jobName (string) — Nome interno do emprego
• jobLabel (string) — Nome exibido do emprego
• grade (number) — Número do cargo
• gradeLabel (string) — Nome exibido do cargo

meuScript:onDutyChange (Cliente)

Disparado quando o status de serviço muda.

AddEventHandler('meuScript:onDutyChange', function(onDuty)
    if onDuty then
        print('Você entrou em serviço')
    else
        print('Você saiu de serviço')
    end
end)

Parâmetros:

• onDuty (boolean) — true se entrou em serviço, false se saiu

Módulo: Inventário — Eventos

meuScript:itemUsed (Servidor)

Disparado quando um jogador usa um item.

AddEventHandler('meuScript:itemUsed', function(itemName, quantity)
    local source = source
    print('Jogador ' .. source .. ' usou ' .. itemName)
end)

Parâmetros:

• itemName (string) — Nome interno do item usado
• quantity (number) — Quantidade usada

meuScript:inventoryOpened (Cliente)

Disparado quando o inventário é aberto pelo jogador.

AddEventHandler('meuScript:inventoryOpened', function()
    -- Execute ações quando o inventário abrir
    print('Inventário aberto')
end)

Módulo: Economia — Eventos

meuScript:onMoneyChange (Cliente)

Disparado quando o saldo do jogador é alterado.

AddEventHandler('meuScript:onMoneyChange', function(moneyType, amount, reason)
    -- moneyType: 'cash' ou 'bank'
    -- amount: valor alterado (positivo = recebeu, negativo = perdeu)
    -- reason: string com o motivo da transação
    if amount > 0 then
        print('Você recebeu R$' .. amount .. ' em ' .. moneyType .. ' (' .. reason .. ')')
    else
        print('Você gastou R$' .. math.abs(amount) .. ' em ' .. moneyType)
    end
end)

Parâmetros:

• moneyType (string) — 'cash' ou 'bank'
• amount (number) — Valor alterado (positivo = recebeu, negativo = perdeu)
• reason (string) — Motivo da transação

meuScript:onPayday (Cliente)

Disparado quando o jogador recebe o pagamento de salário.

AddEventHandler('meuScript:onPayday', function(amount, jobLabel)
    print('Você recebeu R$' .. amount .. ' de salário como ' .. jobLabel)
end)

Parâmetros:

• amount (number) — Valor do salário recebido
• jobLabel (string) — Nome exibido do emprego

Módulo: Admin — Eventos

meuScript:onPlayerBanned (Servidor)

Disparado quando um jogador é banido.

AddEventHandler('meuScript:onPlayerBanned', function(targetSource, adminSource, reason, duration)
    -- Integre com seu sistema de logs externo
    print('Jogador ' .. targetSource .. ' banido por ' .. adminSource)
    print('Motivo: ' .. reason .. ' | Duração: ' .. duration)
end)

Parâmetros:

• targetSource (number) — ID do jogador banido
• adminSource (number) — ID do admin que aplicou o ban
• reason (string) — Motivo informado
• duration (string) — Duração do ban (ex: '7d', 'perm')

Use o prefixo do evento configurado em Config.EventPrefix se você personalizou esse valor. Por padrão, o prefixo é o nome do recurso.