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

# Configurações Compartilhadas

> Configurações compartilhadas entre client e server: itens coletáveis, estatísticas e permissões

# ⚙️ Configurações Compartilhadas

Estas configurações são utilizadas tanto pelo client quanto pelo server. Localizadas em `config/shared/config.lua`.

***

## 🎁 Sistema de Prêmios Bônus

Multiplicador de prêmio bônus que pode ser aplicado às corridas.

```lua theme={null}
Config.bonusPrize = {
    min = 1.0,
    max = 3.0
}
```

| Propriedade | Tipo     | Descrição            |
| ----------- | -------- | -------------------- |
| `min`       | `number` | Multiplicador mínimo |
| `max`       | `number` | Multiplicador máximo |

<Info>
  O administrador pode definir o multiplicador de cada corrida entre esses valores no painel administrativo.
</Info>

***

## 📊 Sistema de Estatísticas

Configurações do sistema de estatísticas e histórico de corridas.

```lua theme={null}
Config.Statistics = {
    enabled = true,
    days = 365,
}
```

| Propriedade | Tipo      | Padrão | Descrição                                  |
| ----------- | --------- | ------ | ------------------------------------------ |
| `enabled`   | `boolean` | `true` | Ativa/desativa coleta de estatísticas      |
| `days`      | `number`  | `365`  | Período em dias para calcular estatísticas |

<Tip>
  As estatísticas mostram dados como: total de corridas, vitórias, participações, etc. O painel exibe dados dos últimos X dias configurados.
</Tip>

***

## 🎮 Itens Coletáveis (Power-ups)

<Info>
  Este é um dos sistemas mais robustos do script! Permite adicionar power-ups ao estilo Mario Kart às suas corridas.
</Info>

### Configuração Principal

```lua theme={null}
Config.CollectableItems = {
    enabled = true,
    chanceToHaveItem = 10,
    sortAlgorithm = "weighted",
    sortFor = "all_players",
    singleUse = false,
    replaceItem = false,
    useControl = 38,
    useControlDisplay = "E",
    useMultiplier = true,
    List = { ... }
}
```

### Propriedades Detalhadas

<AccordionGroup>
  <Accordion title="enabled" icon="power-off" defaultOpen>
    | Tipo      | Padrão |
    | --------- | ------ |
    | `boolean` | `true` |

    Ativa ou desativa o sistema de itens coletáveis globalmente em todo o servidor.

    <Warning>
      Mesmo com `enabled = true`, cada corrida precisa ter `collectable_items = true` para que os itens apareçam.
    </Warning>
  </Accordion>

  <Accordion title="chanceToHaveItem" icon="percent">
    | Tipo     | Padrão | Intervalo |
    | -------- | ------ | --------- |
    | `number` | `10`   | 0-100     |

    Porcentagem de chance de ganhar um item ao passar por cada checkpoint.

    **Exemplos:**

    * `10` = 10% de chance por checkpoint
    * `25` = 25% de chance por checkpoint
    * `100` = Sempre ganha item (não recomendado)
  </Accordion>

  <Accordion title="sortAlgorithm" icon="shuffle">
    | Tipo     | Padrão       | Opções                   |
    | -------- | ------------ | ------------------------ |
    | `string` | `"weighted"` | `"random"`, `"weighted"` |

    Define como o item é sorteado:

    | Algoritmo    | Descrição                                |
    | ------------ | ---------------------------------------- |
    | `"random"`   | Todos os itens têm a mesma chance        |
    | `"weighted"` | Itens com maior `weight` têm mais chance |

    <Tip>
      Use `"weighted"` para fazer itens comuns aparecerem mais que itens raros.
    </Tip>
  </Accordion>

  <Accordion title="sortFor" icon="users">
    | Tipo     | Padrão          | Opções                                                    |
    | -------- | --------------- | --------------------------------------------------------- |
    | `string` | `"all_players"` | `"all_players"`, `"first_player"`, `"first_without_item"` |

    Define quem pode ganhar item quando múltiplos jogadores passam pelo checkpoint:

    | Opção                  | Descrição                              |
    | ---------------------- | -------------------------------------- |
    | `"all_players"`        | Todos podem ganhar no mesmo checkpoint |
    | `"first_player"`       | Apenas o primeiro a passar ganha       |
    | `"first_without_item"` | Primeiro SEM item ganha                |
  </Accordion>

  <Accordion title="singleUse" icon="1">
    | Tipo      | Padrão  |
    | --------- | ------- |
    | `boolean` | `false` |

    Se `true`, cada jogador só pode usar **UM** item por corrida inteira.

    <Warning>
      Isso torna a decisão de quando usar o item muito estratégica!
    </Warning>
  </Accordion>

  <Accordion title="replaceItem" icon="rotate">
    | Tipo      | Padrão  |
    | --------- | ------- |
    | `boolean` | `false` |

    Se `true`, coletar um novo item substitui o item atual. Se `false`, o jogador mantém o item atual até usar.
  </Accordion>

  <Accordion title="useControl" icon="keyboard">
    | Tipo     | Padrão |
    | -------- | ------ |
    | `number` | `38`   |

    ID do controle/tecla para usar o item coletado.

    **Controles comuns:**

    | ID | Tecla |
    | -- | ----- |
    | 38 | E     |
    | 47 | G     |
    | 73 | X     |
    | 74 | H     |

    <Card title="Lista de Controles" icon="keyboard" href="https://docs.fivem.net/docs/game-references/controls/">
      Consulte todos os IDs de controle do FiveM
    </Card>
  </Accordion>

  <Accordion title="useControlDisplay" icon="font">
    | Tipo     | Padrão |
    | -------- | ------ |
    | `string` | `"E"`  |

    Texto exibido na interface indicando qual tecla usar. Deve corresponder ao `useControl`.
  </Accordion>

  <Accordion title="useMultiplier" icon="calculator">
    | Tipo      | Padrão |
    | --------- | ------ |
    | `boolean` | `true` |

    Se `true`, aplica o multiplicador de bônus da corrida à chance de ganhar item.

    **Exemplo:**

    * Chance base: 10%
    * Multiplicador da corrida: 2.0
    * Chance final: 20%
  </Accordion>
</AccordionGroup>

***

## 📦 Lista de Itens

Cada item na lista possui estas propriedades:

```lua theme={null}
{
    enabled = true,
    index = "nitro",
    name = Locale("collectable_item_name_nitro"),
    weight = 60,
    rarity = "common",
    duration = 10000,
}
```

| Propriedade | Tipo              | Descrição                                             |
| ----------- | ----------------- | ----------------------------------------------------- |
| `enabled`   | `boolean`         | Se o item está ativo no sorteio                       |
| `index`     | `string`          | Identificador único do item                           |
| `name`      | `string`          | Nome para exibição (use Locale para tradução)         |
| `weight`    | `number`          | Peso no sorteio (maior = mais chance)                 |
| `rarity`    | `string`          | Raridade visual                                       |
| `duration`  | `number` ou `nil` | Duração em ms (`nil` = permanente, `0` = instantâneo) |

### Raridades Disponíveis

| Raridade      | Descrição | Cor Sugerida |
| ------------- | --------- | ------------ |
| `"common"`    | Comum     | Cinza        |
| `"uncommon"`  | Incomum   | Verde        |
| `"rare"`      | Raro      | Azul         |
| `"epic"`      | Épico     | Roxo         |
| `"legendary"` | Lendário  | Dourado      |
| `"mythic"`    | Mítico    | Vermelho     |

### Itens Padrão

<Tabs>
  <Tab title="Nitro" icon="rocket">
    ```lua theme={null}
    {
        enabled = true,
        index = "nitro",
        name = Locale("collectable_item_name_nitro"),
        weight = 60,
        rarity = "common",
        duration = 10000, -- 10 segundos
    }
    ```

    **Efeito:** Boost de velocidade com chamas no escapamento

    **Funções ativadas:**

    * `SetVehicleRocketBoostActive`
    * `SetVehicleNitroEnabled`
    * `ModifyVehicleTopSpeed(vehicle, 50.0)`
  </Tab>

  <Tab title="Impulso de Velocidade" icon="bolt">
    ```lua theme={null}
    {
        enabled = true,
        index = "speed_boost",
        name = Locale("collectable_item_name_speed_boost"),
        weight = 40,
        rarity = "rare",
        duration = 8000, -- 8 segundos
    }
    ```

    **Efeito:** Aumenta a velocidade máxima temporariamente

    **Diferença do Nitro:** Não tem efeito visual de chamas, apenas aumento de velocidade.
  </Tab>

  <Tab title="Fantasma" icon="ghost">
    ```lua theme={null}
    {
        enabled = true,
        index = "ghost",
        name = Locale("collectable_item_name_ghost"),
        weight = 20,
        rarity = "epic",
        duration = nil, -- Até o fim da corrida
    }
    ```

    **Efeito:** Permite atravessar outros veículos

    <Warning>
      Este item dura até o fim da corrida! Use com sabedoria.
    </Warning>
  </Tab>

  <Tab title="Escudo" icon="shield">
    ```lua theme={null}
    {
        enabled = true,
        index = "shield",
        name = Locale("collectable_item_name_shield"),
        weight = 10,
        rarity = "legendary",
        duration = 10000, -- 10 segundos
    }
    ```

    **Efeito:** Proteção contra danos e colisões

    **Efeito visual:** Partícula dourada ao redor do veículo
  </Tab>

  <Tab title="Reparo" icon="wrench">
    ```lua theme={null}
    {
        enabled = true,
        index = "repair",
        name = Locale("collectable_item_name_repair"),
        weight = 5,
        rarity = "mythic",
        duration = 0, -- Efeito instantâneo
    }
    ```

    **Efeito:** Repara completamente o veículo

    **Funções ativadas:**

    * `SetVehicleFixed`
    * `SetVehicleDeformationFixed`
    * `SetVehicleEngineOn`

    <Tip>
      Item mais raro! Peso 5 significa \~5% de chance quando comparado ao Nitro (60).
    </Tip>
  </Tab>
</Tabs>

### Cálculo de Probabilidade (Weighted)

Com o algoritmo `"weighted"`, a chance de cada item é:

$$
\text{Chance} = \frac{\text{weight do item}}{\sum \text{weights de todos os itens}}
$$

**Exemplo com itens padrão:**

| Item        | Weight  | Cálculo | Chance   |
| ----------- | ------- | ------- | -------- |
| Nitro       | 60      | 60/135  | 44.4%    |
| Speed Boost | 40      | 40/135  | 29.6%    |
| Ghost       | 20      | 20/135  | 14.8%    |
| Shield      | 10      | 10/135  | 7.4%     |
| Repair      | 5       | 5/135   | 3.7%     |
| **Total**   | **135** | -       | **100%** |

***

## 🔢 Limites do Sistema

### Limite de Blips na Fila

```lua theme={null}
Config.queueBlipsLimit = {
    min = 1,
    max = nil  -- nil = sem limite
}
```

| Propriedade | Tipo              | Descrição                            |
| ----------- | ----------------- | ------------------------------------ |
| `min`       | `number`          | Mínimo de pontos na fila             |
| `max`       | `number` ou `nil` | Máximo de pontos (`nil` = ilimitado) |

### Limite de Checkpoints por Rota

```lua theme={null}
Config.raceCheckpointsLimit = {
    min = 1,
    max = nil  -- nil = sem limite
}
```

| Propriedade | Tipo              | Descrição                                 |
| ----------- | ----------------- | ----------------------------------------- |
| `min`       | `number`          | Mínimo de checkpoints por rota            |
| `max`       | `number` ou `nil` | Máximo de checkpoints (`nil` = ilimitado) |

***

## ⏱️ Timeouts e Cooldowns

```lua theme={null}
-- Tempo limite em segundos para entrar na fila de uma corrida
Config.enterQueueTimeout = 15
```

| Propriedade         | Tipo     | Padrão | Descrição                               |
| ------------------- | -------- | ------ | --------------------------------------- |
| `enterQueueTimeout` | `number` | `15`   | Segundos para confirmar entrada na fila |

***

## 🔐 Sistema de Permissões

Define quem pode acessar cada funcionalidade do script.

```lua theme={null}
Config.Permissions = {
    ["race_management"] = "ADMIN",
    ["routes_creation"] = "USER",
    ["routes_statistics"] = "ADMIN",
    ["routes_management"] = "ADMIN",
    ["race_rankings"] = "USER",
    ["race_main"] = "USER",
    ["race_race"] = "USER",
    ["settings"] = "USER",
}
```

### Níveis de Permissão

| Nível     | Descrição                           |
| --------- | ----------------------------------- |
| `"USER"`  | Qualquer jogador pode acessar       |
| `"ADMIN"` | Apenas administradores do framework |

### Permissões Disponíveis

| Chave               | Descrição                     | Padrão |
| ------------------- | ----------------------------- | ------ |
| `race_management`   | Criar/editar/deletar corridas | ADMIN  |
| `routes_creation`   | Criar novas rotas             | USER   |
| `routes_statistics` | Ver estatísticas detalhadas   | ADMIN  |
| `routes_management` | Editar/deletar rotas          | ADMIN  |
| `race_rankings`     | Ver rankings                  | USER   |
| `race_main`         | Acessar menu principal        | USER   |
| `race_race`         | Participar de corridas        | USER   |
| `settings`          | Acessar configurações         | USER   |

<Tip>
  Para bloquear que players criem rotas, altere:

  ```lua theme={null}
  ["routes_creation"] = "ADMIN",
  ```
</Tip>

***

## 📝 Exemplo Completo

```lua theme={null}
-- config/shared/config.lua
Config = {}

-- Sistema de Prêmios
Config.bonusPrize = {
    min = 1.0,
    max = 5.0
}

-- Estatísticas
Config.Statistics = {
    enabled = true,
    days = 30, -- Últimos 30 dias
}

-- Itens Coletáveis
Config.CollectableItems = {
    enabled = true,
    chanceToHaveItem = 15,
    sortAlgorithm = "weighted",
    sortFor = "all_players",
    singleUse = false,
    replaceItem = true,
    useControl = 38,
    useControlDisplay = "E",
    useMultiplier = true,
    List = {
        {
            enabled = true,
            index = "nitro",
            name = Locale("collectable_item_name_nitro"),
            weight = 50,
            rarity = "common",
            duration = 8000,
        },
        {
            enabled = true,
            index = "speed_boost",
            name = Locale("collectable_item_name_speed_boost"),
            weight = 30,
            rarity = "rare",
            duration = 6000,
        },
        {
            enabled = true,
            index = "ghost",
            name = Locale("collectable_item_name_ghost"),
            weight = 15,
            rarity = "epic",
            duration = 15000, -- 15 segundos em vez de permanente
        },
        {
            enabled = true,
            index = "shield",
            name = Locale("collectable_item_name_shield"),
            weight = 10,
            rarity = "legendary",
            duration = 8000,
        },
        {
            enabled = true,
            index = "repair",
            name = Locale("collectable_item_name_repair"),
            weight = 5,
            rarity = "mythic",
            duration = 0,
        },
    },
}

-- Limites
Config.queueBlipsLimit = { min = 2, max = 10 }
Config.raceCheckpointsLimit = { min = 5, max = 50 }

-- Timeouts
Config.enterQueueTimeout = 30

-- Permissões
Config.Permissions = {
    ["race_management"] = "ADMIN",
    ["routes_creation"] = "USER",
    ["routes_statistics"] = "ADMIN",
    ["routes_management"] = "ADMIN",
    ["race_rankings"] = "USER",
    ["race_main"] = "USER",
    ["race_race"] = "USER",
    ["settings"] = "USER",
}
```