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

# Handlers & Eventos

> Documentação dos event handlers e callbacks personalizáveis

# ⚡ Handlers & Eventos

Os handlers são funções executadas automaticamente em momentos específicos da corrida. Você pode personalizá-los para integrar com outros scripts ou adicionar funcionalidades.

***

## 🖥️ Handlers Client

Localizados em `config/client/functions/handlers.lua`.

### Inicialização

```lua theme={null}
Handlers = {}

local _Sounds = {}

function Handlers.init(sounds)
    _Sounds = sounds
end
```

<Info>
  O método `init` é chamado automaticamente e injeta as dependências necessárias.
</Info>

***

### onRaceStart

Executado quando a corrida inicia para o jogador local.

```lua theme={null}
function Handlers.onRaceStart(vehicle, routeId, raceId, players)
    
end
```

**Parâmetros:**

| Parâmetro | Tipo     | Descrição                       |
| --------- | -------- | ------------------------------- |
| `vehicle` | `number` | Entity ID do veículo do jogador |
| `routeId` | `number` | ID da rota da corrida           |
| `raceId`  | `number` | ID da corrida                   |
| `players` | `table`  | Lista de jogadores              |

**Estrutura de `players`:**

```lua theme={null}
{
    {
        source = 1,
        nickname = "Player1",
        self = true  -- É o jogador local
    },
    {
        source = 2,
        nickname = "Player2",
        self = false
    }
}
```

<Tip>
  **Exemplo de uso:** Tocar um som customizado, iniciar uma animação, notificar outros scripts.
</Tip>

***

### onRaceFinish

Executado quando o jogador local termina a corrida.

```lua theme={null}
function Handlers.onRaceFinish(success)
end
```

**Parâmetros:**

| Parâmetro | Tipo      | Descrição                              |
| --------- | --------- | -------------------------------------- |
| `success` | `boolean` | `true` se completou, `false` se falhou |

<Tip>
  **Exemplo de uso:** Exibir animação de vitória/derrota, notificar sistema de achievements.
</Tip>

***

### onReachCheckpoint

Executado quando o jogador local passa por um checkpoint.

```lua theme={null}
function Handlers.onReachCheckpoint(checkpointId, lastCheckpointId)
    local isLastCheckpoint = checkpointId == lastCheckpointId
    _Sounds.play(isLastCheckpoint and "finish_success" or "reach_checkpoint")
end
```

**Parâmetros:**

| Parâmetro          | Tipo     | Descrição                       |
| ------------------ | -------- | ------------------------------- |
| `checkpointId`     | `number` | ID do checkpoint atingido       |
| `lastCheckpointId` | `number` | ID do último checkpoint da rota |

***

### onAnyPlayerReachCheckpoint

Executado quando **qualquer** jogador na corrida atinge um checkpoint.

```lua theme={null}
function Handlers.onAnyPlayerReachCheckpoint(playerData, checkpointId)

end
```

**Parâmetros:**

| Parâmetro      | Tipo     | Descrição        |
| -------------- | -------- | ---------------- |
| `playerData`   | `table`  | Dados do jogador |
| `checkpointId` | `number` | ID do checkpoint |

**Estrutura de `playerData`:**

```lua theme={null}
{
    source = 1,
    finished = false,  -- Se o jogador terminou a corrida
    position = 2       -- Posição atual na corrida
}
```

***

### onAnyPlayerLeaveRace

Executado quando outro jogador sai da corrida.

```lua theme={null}
function Handlers.onAnyPlayerLeaveRace(source)
end
```

**Parâmetros:**

| Parâmetro | Tipo     | Descrição                         |
| --------- | -------- | --------------------------------- |
| `source`  | `number` | Player source do jogador que saiu |

***

## 🖧 Handlers Server

Localizados em `config/server/functions/handlers.lua`.

### Inicialização

```lua theme={null}
Handlers = {}

local _Webhooks = {}
local _Police = {}
local _Rewards = {}

function Handlers.init(webhooks, police, rewards)
    _Webhooks = webhooks
    _Police = police
    _Rewards = rewards
end
```

***

### onStartRace

Executado quando uma corrida é iniciada no servidor.

```lua theme={null}
function Handlers.onStartRace(raceId, routeId, playersList, raceConfigs)
    -- Enviar webhook
    _Webhooks.emitRaceStart(
        raceId,
        routeId,
        raceConfigs.name,
        raceConfigs.startBlip.x .. ", " .. raceConfigs.startBlip.y .. ", " .. raceConfigs.startBlip.z,
        playersList
    )

    -- Alertar polícia se corrida for ilegal
    if raceConfigs.isIllegal then
        _Police.emitEvent(function(policeSource)
            Notification(policeSource, "yellow", Locale("police_alert_race_started", {raceConfigs.name}), 7000)
        end)
    end
end
```

**Parâmetros:**

| Parâmetro     | Tipo     | Descrição                        |
| ------------- | -------- | -------------------------------- |
| `raceId`      | `number` | ID da corrida                    |
| `routeId`     | `number` | ID da rota                       |
| `playersList` | `table`  | Lista de jogadores participantes |
| `raceConfigs` | `table`  | Configurações da corrida         |

**Estrutura de `playersList`:**

```lua theme={null}
{
    { userId = "abc123", nickname = "Player1", source = 1 },
    { userId = "def456", nickname = "Player2", source = 2 }
}
```

**Propriedades importantes de `raceConfigs`:**

| Propriedade        | Tipo      | Descrição               |
| ------------------ | --------- | ----------------------- |
| `name`             | `string`  | Nome da corrida         |
| `startBlip`        | `vector3` | Coordenadas de início   |
| `isIllegal`        | `boolean` | Se é corrida ilegal     |
| `bonusPrize`       | `number`  | Multiplicador de prêmio |
| `collectableItems` | `boolean` | Se tem power-ups        |

***

### onPlayerFinishRace

Executado quando um jogador finaliza a corrida.

```lua theme={null}
function Handlers.onPlayerFinishRace(playerData, raceId, successfully, raceConfigs, extraData)
    local source = tonumber(playerData.source)

    -- Enviar webhook
    _Webhooks.emitRaceFinish(
        raceId,
        raceConfigs.name,
        successfully,
        extraData,
        playerData
    )

    -- Entregar recompensa ou aplicar penalidade
    if successfully then
        _Rewards.giveSuccessReward(source, raceId, raceConfigs, extraData)
    else
        _Rewards.applyFailPenalty(source, raceId, raceConfigs, extraData)
    end
end
```

**Parâmetros:**

| Parâmetro      | Tipo      | Descrição                |
| -------------- | --------- | ------------------------ |
| `playerData`   | `table`   | Dados do jogador         |
| `raceId`       | `number`  | ID da corrida            |
| `successfully` | `boolean` | Se completou com sucesso |
| `raceConfigs`  | `table`   | Configurações da corrida |
| `extraData`    | `table`   | Dados extras             |

**Estrutura de `extraData`:**

```lua theme={null}
{
    position = 1  -- Posição final do jogador
}
```

***

### onPlayerReachCheckpoint

Executado quando um jogador atinge um checkpoint.

```lua theme={null}
function Handlers.onPlayerReachCheckpoint(source, raceId, checkpointId, raceConfigs)
    -- Atualizar posição para a polícia
    _Police.updateRacePosition(source)

    -- Verificar itens coletáveis
    if raceConfigs.collectableItems then
        CollectableItems.reachCheckpoint(source, raceId, checkpointId, raceConfigs)
    end
end
```

**Parâmetros:**

| Parâmetro      | Tipo     | Descrição                |
| -------------- | -------- | ------------------------ |
| `source`       | `number` | Player source            |
| `raceId`       | `number` | ID da corrida            |
| `checkpointId` | `number` | ID do checkpoint         |
| `raceConfigs`  | `table`  | Configurações da corrida |

***

### onRaceClear

Executado quando a corrida termina ou é resetada.

```lua theme={null}
function Handlers.onRaceClear(raceId)
    CollectableItems.clearRaceData(raceId)
end
```

**Parâmetros:**

| Parâmetro | Tipo     | Descrição     |
| --------- | -------- | ------------- |
| `raceId`  | `number` | ID da corrida |

***

## 📝 Exemplos de Personalização

### Integração com Sistema de XP

```lua theme={null}
-- config/server/functions/handlers.lua

function Handlers.onPlayerFinishRace(playerData, raceId, successfully, raceConfigs, extraData)
    local source = tonumber(playerData.source)
    
    -- Código original...
    _Webhooks.emitRaceFinish(raceId, raceConfigs.name, successfully, extraData, playerData)
    
    if successfully then
        _Rewards.giveSuccessReward(source, raceId, raceConfigs, extraData)
        
        -- ADICIONAR: Sistema de XP
        local xpGained = 100 * (5 - extraData.position) -- Mais XP para posições melhores
        TriggerEvent("seu_script_xp:addXP", source, xpGained)
    else
        _Rewards.applyFailPenalty(source, raceId, raceConfigs, extraData)
    end
end
```

### Notificação Customizada ao Terminar

```lua theme={null}
-- config/client/functions/handlers.lua

function Handlers.onRaceFinish(success)
    -- ADICIONAR: Efeito visual
    if success then
        -- Confete ou efeito de vitória
        exports.seu_script_efeitos:playEffect("confetti")
    else
        -- Efeito de derrota
        exports.seu_script_efeitos:playEffect("smoke")
    end
end
```

### Integração com Sistema de Apostas

```lua theme={null}
-- config/server/functions/handlers.lua

function Handlers.onStartRace(raceId, routeId, playersList, raceConfigs)
    -- Código original...
    _Webhooks.emitRaceStart(...)
    
    if raceConfigs.isIllegal then
        _Police.emitEvent(...)
    end
    
    -- ADICIONAR: Notificar sistema de apostas
    local playerNames = {}
    for _, player in pairs(playersList) do
        table.insert(playerNames, player.nickname)
    end
    TriggerEvent("seu_script_apostas:raceStarted", raceId, playerNames)
end
```

***

## 🔗 Módulos Disponíveis

### Client

| Módulo    | Descrição       | Funções Principais |
| --------- | --------------- | ------------------ |
| `_Sounds` | Sistema de sons | `play(soundName)`  |

### Server

| Módulo      | Descrição              | Funções Principais                          |
| ----------- | ---------------------- | ------------------------------------------- |
| `_Webhooks` | Discord webhooks       | `emitRaceStart`, `emitRaceFinish`           |
| `_Police`   | Sistema de polícia     | `emitEvent(callback)`, `updateRacePosition` |
| `_Rewards`  | Sistema de recompensas | `giveSuccessReward`, `applyFailPenalty`     |

***

## ⚠️ Boas Práticas

<Warning>
  **NÃO remova** as chamadas originais dos handlers! Elas são necessárias para o funcionamento correto do script.
</Warning>

<Tip>
  Sempre adicione seu código **após** as chamadas originais para garantir que a lógica base seja executada primeiro.
</Tip>

```lua theme={null}
function Handlers.onRaceFinish(success)
    -- ✅ Seu código customizado
    MyCustomFunction(success)
end
```