> ## 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. # Funções Server > Documentação das funções do lado do servidor disponíveis para personalização # 🖧 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. ```lua theme={null} function Permissions.init(framework) ``` *** ### Permissions.check Verifica se um jogador tem permissão para uma ação. ```lua theme={null} 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:** ```lua theme={null} 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. ```lua theme={null} function Rewards.init(framework) ``` *** ### Rewards.positionBonus Tabela de bônus por posição final. ```lua theme={null} Rewards.positionBonus = { [1] = 0, -- 1º lugar [2] = 0, -- 2º lugar [3] = 0, -- 3º lugar } ``` **Personalizando:** ```lua theme={null} 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. ```lua theme={null} 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:** ```lua theme={null} return ParseInt((math.random(min, max) + posBonus) * bonus) ``` *** ### Rewards.giveSuccessReward Entrega a recompensa ao jogador que completou com sucesso. ```lua theme={null} function Rewards.giveSuccessReward(source, raceId, raceConfigs, extraData) ``` **Comportamento por framework:** Entrega como item: | Framework | Item | | ------------- | -------------- | | vrp.crnetwork | `dollarsroll` | | vrp.crv5 | `dollars2` | | vrp.crv3 | `dollars2` | | default | `dinheirosujo` | ```lua theme={null} user.giveItem(item, reward, true) ``` Deposita no banco: ```lua theme={null} user.paymentBank(reward) ``` *** ### Rewards.applyFailPenalty Aplica penalidade ao jogador que falhou. ```lua theme={null} function Rewards.applyFailPenalty(source, raceId, raceConfigs, extraData) ``` **Comportamento padrão:** ```lua theme={null} 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. ```lua theme={null} function Police.init(framework) ``` *** ### Police.emitEvent Dispara um evento para todos os policiais online. ```lua theme={null} function Police.emitEvent(fn) ``` **Parâmetros:** | Parâmetro | Tipo | Descrição | | --------- | ---------- | ------------------------------------- | | `fn` | `function` | Callback executado para cada policial | **Exemplo:** ```lua theme={null} Police.emitEvent(function(policeSource) Notification(policeSource, "yellow", "Corrida ilegal detectada!") end) ``` *** ### Police.updateRacePosition Atualiza a posição de um corredor para os policiais. ```lua theme={null} function Police.updateRacePosition(source) ``` Obtém as coordenadas do jogador e envia para todos os policiais: ```lua theme={null} TriggerClientEvent("dk_races/updateRaceChasePosition", policeSource, coords) ``` *** ## 📢 Webhooks (`webhooks.lua`) Sistema de notificações Discord. ### emitWebhook (interno) Função base para enviar webhooks. ```lua theme={null} local function emitWebhook(webhook, title, description, fields) ``` *** ### Webhooks.emitRaceStart Envia notificação quando uma corrida inicia. ```lua theme={null} 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. ```lua theme={null} 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. ```lua theme={null} function Validators.init(permissions, items) ``` *** ### Validators.canEnterRace Valida se o jogador pode entrar na corrida. ```lua theme={null} function Validators.canEnterRace(source, raceId, routeId, raceStatus, itemData) ``` **Validações realizadas:** 1. ✅ Permissão para participar de corridas 2. ✅ Possui o item necessário (se configurado) **Retorno:** `boolean` *** ### Validators.nicknameValidation Valida o nickname do jogador. ```lua theme={null} function Validators.nicknameValidation(source, nickname, params) ``` **Validações realizadas:** 1. ✅ Tamanho entre 3 e 20 caracteres 2. ✅ Não está vazio 3. ✅ 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. ```lua theme={null} 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. ```lua theme={null} 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. ```lua theme={null} 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. ```lua theme={null} function Framework.getPermissionLevel(source) ``` **Retorno:** `string` - `"USER"` ou `"ADMIN"` *** ### Framework.getPlayersByPermission Lista todos os jogadores com determinada permissão. ```lua theme={null} 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. ```lua theme={null} function CollectableItems.reachCheckpoint(source, raceId, checkpointId, raceConfigs) ``` **Fluxo:** 1. Verifica se sistema está habilitado 2. Verifica regras de `sortFor` 3. Verifica se jogador já tem item (`replaceItem`) 4. Sorteia item baseado no algoritmo 5. Entrega item ao jogador *** ### CollectableItems.clearRaceData Limpa dados de uma corrida finalizada. ```lua theme={null} function CollectableItems.clearRaceData(raceId) ``` *** ### CollectableItems.useItem Processa o uso de um item pelo jogador. ```lua theme={null} 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. ```lua theme={null} 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. ```lua theme={null} RegisterServerCallback("dk_races/canOpenPanel", function(source, params) local permissionLevel = Config.Functions.getPermissionLevel(source) return { canOpen = true, permissionLevel = permissionLevel } end) ``` *** ## 📋 Exemplo: Integrando Sistema de Log ```lua theme={null} -- 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 ```lua theme={null} -- 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 ```