⚡ 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

Handlers = {}

local _Sounds = {}

function Handlers.init(sounds)
    _Sounds = sounds
end

O método init é chamado automaticamente e injeta as dependências necessárias.

onRaceStart

Executado quando a corrida inicia para o jogador local.

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:

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

Exemplo de uso: Tocar um som customizado, iniciar uma animação, notificar outros scripts.

onRaceFinish

Executado quando o jogador local termina a corrida.

function Handlers.onRaceFinish(success)
end

Parâmetros:

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

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

onReachCheckpoint

Executado quando o jogador local passa por um checkpoint.

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.

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:

{
    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.

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

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.

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:

{
    { 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.

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:

{
    position = 1  -- Posição final do jogador
}

onPlayerReachCheckpoint

Executado quando um jogador atinge um checkpoint.

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.

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

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

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

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

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

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

function Handlers.onRaceFinish(success)
    -- ✅ Seu código customizado
    MyCustomFunction(success)
end

Informações Gerais

Scripts

Handlers & Eventos

⚡ Handlers & Eventos

🖥️ Handlers Client

Inicialização

onRaceStart

onRaceFinish

onReachCheckpoint

onAnyPlayerReachCheckpoint

onAnyPlayerLeaveRace

🖧 Handlers Server

Inicialização

onStartRace

onPlayerFinishRace

onPlayerReachCheckpoint

onRaceClear

📝 Exemplos de Personalização

Integração com Sistema de XP

Notificação Customizada ao Terminar

Integração com Sistema de Apostas

🔗 Módulos Disponíveis

Client

Server

⚠️ Boas Práticas

​⚡ Handlers & Eventos

​🖥️ Handlers Client

​Inicialização

​onRaceStart

​onRaceFinish

​onReachCheckpoint

​onAnyPlayerReachCheckpoint

​onAnyPlayerLeaveRace

​🖧 Handlers Server

​Inicialização

​onStartRace

​onPlayerFinishRace

​onPlayerReachCheckpoint

​onRaceClear

​📝 Exemplos de Personalização

​Integração com Sistema de XP

​Notificação Customizada ao Terminar

​Integração com Sistema de Apostas

​🔗 Módulos Disponíveis

​Client

​Server

​⚠️ Boas Práticas

⚡ Handlers & Eventos

🖥️ Handlers Client

Inicialização

onRaceStart

onRaceFinish

onReachCheckpoint

onAnyPlayerReachCheckpoint

onAnyPlayerLeaveRace

🖧 Handlers Server

Inicialização

onStartRace

onPlayerFinishRace

onPlayerReachCheckpoint

onRaceClear

📝 Exemplos de Personalização

Integração com Sistema de XP

Notificação Customizada ao Terminar

Integração com Sistema de Apostas

🔗 Módulos Disponíveis

Client

Server

⚠️ Boas Práticas