🖧 Funções Server

Esta página documenta todas as funções disponíveis no lado do servidor que você pode usar ou personalizar.

🔐 Permissões (`permissions.lua`)

Sistema de controle de acesso às funcionalidades.

Permissions.init

Inicializa o módulo com o framework.

function Permissions.init(framework)

Permissions.check

Verifica se um jogador tem permissão para uma ação.

function Permissions.check(source, mode, action)

Parâmetros:

Parâmetro	Tipo	Descrição
`source`	`number`	Player source
`mode`	`string`	Modo de permissão (chave em Config.Permissions)
`action`	`string`	Nome da ação (para logging)

Retorno: boolean Exemplo:

if Permissions.check(source, "race_management", "create-race") then
    -- Jogador pode criar corridas
end

💰 Recompensas (`rewards.lua`)

Sistema de cálculo e entrega de prêmios.

Rewards.init

Inicializa o módulo com o framework.

function Rewards.init(framework)

Rewards.positionBonus

Tabela de bônus por posição final.

Rewards.positionBonus = {
    [1] = 0,  -- 1º lugar
    [2] = 0,  -- 2º lugar
    [3] = 0,  -- 3º lugar
}

Personalizando:

Rewards.positionBonus = {
    [1] = 2000,  -- 1º lugar: +$2000
    [2] = 1000,  -- 2º lugar: +$1000
    [3] = 500,   -- 3º lugar: +$500
}

Rewards.calculate

Calcula o prêmio final baseado na posição.

function Rewards.calculate(bonus, min, max, position)

Parâmetros:

Parâmetro	Tipo	Descrição
`bonus`	`number`	Multiplicador de bônus da corrida
`min`	`number`	Recompensa mínima
`max`	`number`	Recompensa máxima
`position`	`number`	Posição final do jogador

Retorno: number - Prêmio calculado Fórmula:

return ParseInt((math.random(min, max) + posBonus) * bonus)

Rewards.giveSuccessReward

Entrega a recompensa ao jogador que completou com sucesso.

function Rewards.giveSuccessReward(source, raceId, raceConfigs, extraData)

Comportamento por framework:

VRP
Outros

Entrega como item:

Framework	Item
vrp.crnetwork	`dollarsroll`
vrp.crv5	`dollars2`
vrp.crv3	`dollars2`
default	`dinheirosujo`

user.giveItem(item, reward, true)

Deposita no banco:

user.paymentBank(reward)

Rewards.applyFailPenalty

Aplica penalidade ao jogador que falhou.

function Rewards.applyFailPenalty(source, raceId, raceConfigs, extraData)

Comportamento padrão:

if raceConfigs.isExplosive then
    TriggerClientEvent("dk_races/triggerExplosion", source)
end

🚔 Polícia (`police.lua`)

Sistema de integração com policiais.

Police.init

Inicializa o módulo com o framework.

function Police.init(framework)

Police.emitEvent

Dispara um evento para todos os policiais online.

function Police.emitEvent(fn)

Parâmetros:

Parâmetro	Tipo	Descrição
`fn`	`function`	Callback executado para cada policial

Exemplo:

Police.emitEvent(function(policeSource)
    Notification(policeSource, "yellow", "Corrida ilegal detectada!")
end)

Police.updateRacePosition

Atualiza a posição de um corredor para os policiais.

function Police.updateRacePosition(source)

Obtém as coordenadas do jogador e envia para todos os policiais:

TriggerClientEvent("dk_races/updateRaceChasePosition", policeSource, coords)

📢 Webhooks (`webhooks.lua`)

Sistema de notificações Discord.

emitWebhook (interno)

Função base para enviar webhooks.

local function emitWebhook(webhook, title, description, fields)

Webhooks.emitRaceStart

Envia notificação quando uma corrida inicia.

function Webhooks.emitRaceStart(raceId, routeId, raceName, raceCoords, playersList)

Campos enviados:

Campo	Descrição
ID da Corrida	Identificador único
ID da Rota	Rota selecionada
Local de Início	Coordenadas
Jogadores	Lista de participantes

Webhooks.emitRaceFinish

Envia notificação quando um jogador finaliza.

function Webhooks.emitRaceFinish(raceId, raceName, successfully, extraData, playerData)

Campos enviados:

Campo	Descrição
Nome da Corrida	Identificação
Status	Sucesso/Falha
Posição	Posição final
Dados do Jogador	ID e nickname

✅ Validators (`validators.lua`)

Validações do lado do servidor.

Validators.init

Inicializa com dependências.

function Validators.init(permissions, items)

Validators.canEnterRace

Valida se o jogador pode entrar na corrida.

function Validators.canEnterRace(source, raceId, routeId, raceStatus, itemData)

Validações realizadas:

✅ Permissão para participar de corridas
✅ Possui o item necessário (se configurado)

Retorno: boolean

Validators.nicknameValidation

Valida o nickname do jogador.

function Validators.nicknameValidation(source, nickname, params)

Validações realizadas:

✅ Tamanho entre 3 e 20 caracteres
✅ Não está vazio
✅ Cooldown respeitado (para atualizações)

Parâmetros de params:

Propriedade	Tipo	Descrição
`action`	`string`	`"create"` ou `"update"`
`lastUpdatedAt`	`number`	Timestamp da última alteração

📦 Itens (`items.lua`)

Sistema de verificação de itens.

Items.tryGet

Tenta obter um item do inventário do jogador.

function Items.tryGet(source, itemData)

Parâmetros:

Parâmetro	Tipo	Descrição
`source`	`number`	Player source
`itemData`	`table`	`{index = "item_name", amount = 1}`

Retorno: boolean - Se o jogador possui o item

🚗 Veículos (`vehicles.lua`)

Funções relacionadas a veículos.

🔗 Framework (`framework.lua`)

Integração com diferentes frameworks.

Framework.getName

Retorna o nome do framework detectado.

function Framework.getName()

Retornos possíveis:

Retorno	Framework
`"vrp.crnetwork"`	VRP CRNetwork
`"vrp.vrpex"`	VRP vRPEX
`"vrp.crv3"`	VRP CRv3
`"vrp.crv5"`	VRP CRv5
`"esx"`	ESX
`"qbcore"`	QBCore
`"_nofw"`	Standalone

Framework.getPlayer

Obtém o objeto do jogador do framework.

function Framework.getPlayer(source)

Retorno: Objeto do jogador com métodos específicos do framework.

Framework.getPermissionLevel

Obtém o nível de permissão do jogador.

function Framework.getPermissionLevel(source)

Retorno: string - "USER" ou "ADMIN"

Framework.getPlayersByPermission

Lista todos os jogadores com determinada permissão.

function Framework.getPlayersByPermission(permission)

Usado por: Sistema de polícia para listar policiais online.

🎁 Itens Coletáveis Server (`collectable_items.lua`)

Lógica de sorteio e gerenciamento de power-ups.

CollectableItems.reachCheckpoint

Processa a chegada em um checkpoint e sorteia item.

function CollectableItems.reachCheckpoint(source, raceId, checkpointId, raceConfigs)

Fluxo:

Verifica se sistema está habilitado
Verifica regras de sortFor
Verifica se jogador já tem item (replaceItem)
Sorteia item baseado no algoritmo
Entrega item ao jogador

CollectableItems.clearRaceData

Limpa dados de uma corrida finalizada.

function CollectableItems.clearRaceData(raceId)

CollectableItems.useItem

Processa o uso de um item pelo jogador.

function CollectableItems.useItem(source, itemIndex, raceId, raceConfigs, playersList)

Retorno: boolean, string? - Sucesso e mensagem de erro opcional

📝 Comandos e Callbacks

Comando: /rcadmin

Abre o painel administrativo.

RegisterCommand("rcadmin", function(source)
    if not Config.Functions.checkPermission(source, "admin", "open-race-admin") then
        Notification(source, "red", Locale("not_allowed"))
        return
    end
    TriggerClientEvent("dk_races/openAdmin", source)
end)

Callback: dk_races/canOpenPanel

Verifica se o jogador pode abrir o painel.

RegisterServerCallback("dk_races/canOpenPanel", function(source, params)
    local permissionLevel = Config.Functions.getPermissionLevel(source)
    return {
        canOpen = true,
        permissionLevel = permissionLevel
    }
end)

📋 Exemplo: Integrando Sistema de Log

-- Em 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: Log personalizado
        exports['seu_sistema_log']:log({
            tipo = "race_finished",
            jogador = playerData.nickname,
            corrida = raceConfigs.name,
            posicao = extraData.position,
            timestamp = os.time()
        })
    else
        _Rewards.applyFailPenalty(source, raceId, raceConfigs, extraData)
    end
end

📋 Exemplo: Customizando Recompensas

-- Em config/server/functions/rewards.lua

-- Bônus progressivo por posição
Rewards.positionBonus = {
    [1] = 5000,  -- Campeão
    [2] = 2500,  -- Vice
    [3] = 1000,  -- Terceiro
    [4] = 500,   -- Quarto
    [5] = 250,   -- Quinto
}

-- Recompensa extra para quem terminar sem usar itens
function Rewards.giveSuccessReward(source, raceId, raceConfigs, extraData)
    local user = _Framework.getPlayer(source)
    if not user then return end

    local reward = Rewards.calculate(
        raceConfigs.bonusPrize,
        raceConfigs.rewardMin,
        raceConfigs.rewardMax,
        extraData.position
    )

    -- ADICIONAR: Bônus se não usou item coletável
    if not extraData.usedCollectableItem then
        reward = reward * 1.25  -- +25% de bônus
        Notification(source, "green", "Bônus de 25% por não usar power-ups!")
    end

    -- Entrega padrão
    user.paymentBank(reward)
end

Informações Gerais

Scripts

Documentation Index

​🖧 Funções Server

​🔐 Permissões (permissions.lua)

​Permissions.init

​Permissions.check

​💰 Recompensas (rewards.lua)

​Rewards.init

​Rewards.positionBonus

​Rewards.calculate

​Rewards.giveSuccessReward

​Rewards.applyFailPenalty

​🚔 Polícia (police.lua)

​Police.init

​Police.emitEvent

​Police.updateRacePosition

​📢 Webhooks (webhooks.lua)

​emitWebhook (interno)

​Webhooks.emitRaceStart

​Webhooks.emitRaceFinish

​✅ Validators (validators.lua)

​Validators.init

​Validators.canEnterRace

​Validators.nicknameValidation

​📦 Itens (items.lua)

​Items.tryGet

​🚗 Veículos (vehicles.lua)

​🔗 Framework (framework.lua)

​Framework.getName

​Framework.getPlayer

​Framework.getPermissionLevel

​Framework.getPlayersByPermission

​🎁 Itens Coletáveis Server (collectable_items.lua)

​CollectableItems.reachCheckpoint

​CollectableItems.clearRaceData

​CollectableItems.useItem

​📝 Comandos e Callbacks

​Comando: /rcadmin

​Callback: dk_races/canOpenPanel

​📋 Exemplo: Integrando Sistema de Log

​📋 Exemplo: Customizando Recompensas

🖧 Funções Server

🔐 Permissões (`permissions.lua`)

Permissions.init

Permissions.check

💰 Recompensas (`rewards.lua`)

Rewards.init

Rewards.positionBonus

Rewards.calculate

Rewards.giveSuccessReward

Rewards.applyFailPenalty

🚔 Polícia (`police.lua`)

Police.init

Police.emitEvent

Police.updateRacePosition

📢 Webhooks (`webhooks.lua`)

emitWebhook (interno)

Webhooks.emitRaceStart

Webhooks.emitRaceFinish

✅ Validators (`validators.lua`)

Validators.init

Validators.canEnterRace

Validators.nicknameValidation

📦 Itens (`items.lua`)

Items.tryGet

🚗 Veículos (`vehicles.lua`)

🔗 Framework (`framework.lua`)

Framework.getName

Framework.getPlayer

Framework.getPermissionLevel

Framework.getPlayersByPermission

🎁 Itens Coletáveis Server (`collectable_items.lua`)

CollectableItems.reachCheckpoint

CollectableItems.clearRaceData

CollectableItems.useItem

📝 Comandos e Callbacks

Comando: /rcadmin

Callback: dk_races/canOpenPanel

📋 Exemplo: Integrando Sistema de Log

📋 Exemplo: Customizando Recompensas