> ## Documentation Index
> Fetch the complete documentation index at: https://docs.temacstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```lua theme={null}
-- 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):

```lua theme={null}
-- 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):

```lua theme={null}
-- 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)
```

<Warning>
  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.
</Warning>

## Como Disparar Eventos com TriggerClientEvent

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

```lua theme={null}
-- 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.

```lua theme={null}
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.

```lua theme={null}
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.

```lua theme={null}
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.

```lua theme={null}
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.

```lua theme={null}
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.

```lua theme={null}
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.

```lua theme={null}
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'`)

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