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

# five-tuning

> Tuning veicular (estética e performance) com câmera orbital, NUI em React e pacote de áudios/assets próprio: Pops & Bangs, Westgate, suspensão a ar, neon, xenon, camber, offset, remap (handling) e purgador.

O **five-tuning** é o recurso de modificação de veículos integrado ao vRP. Abre um menu NUI com câmera cinematográfica e aplica modificações **vinculadas à placa** (não ao slot de garagem), persistidas em banco e sincronizadas via state bags. Embute áudio (`dlc_coretuning`) e partículas (`stream/`).

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Suspensão a Ar" icon="arrows-up-down">
    Ajuste de altura da suspensão por veículo.
  </Card>

  <Card title="Neon e Xenon" icon="lightbulb">
    Iluminação customizável aplicada ao veículo.
  </Card>

  <Card title="Camber e Offset" icon="ruler-combined">
    Inclinação e posicionamento das rodas.
  </Card>

  <Card title="Pops & Bangs (Anti-lag)" icon="fire">
    Estouros no escapamento com som e partículas.
  </Card>

  <Card title="Westgate" icon="gauge-high">
    Módulo de tuning dedicado.
  </Card>

  <Card title="Remap (Fueltech/handling)" icon="sliders">
    Edição de campos de `CHandlingData` (torque, ângulo, inércia, freio, tração).
  </Card>

  <Card title="Purgador" icon="wind">
    Efeito de nitro / purga.
  </Card>

  <Card title="Câmera orbital" icon="video">
    Câmera cinematográfica que gira em torno do veículo do jogador.
  </Card>
</CardGroup>

***

## Dependências

<CardGroup cols={2}>
  <Card title="vRP" icon="cube">
    `Passport`, `HasPermission`, `PassportPlate`, `ItemAmount`, `TakeItem`, `GiveItem`, `Query` (tabela `entitydata`), `playAnim`/`stopAnim`.
  </Card>

  <Card title="oxmysql" icon="database">
    Acesso ao banco de dados via `vRP.Query`.
  </Card>

  <Card title="Eventos externos" icon="bell">
    `Notify` e `hud:Active` (eventos de outros recursos).
  </Card>
</CardGroup>

<Info>
  O **core\_logs** é uma dependência opcional.
</Info>

***

## Configuração

<AccordionGroup>
  <Accordion title="config/config.lua — Configurações principais (tabela Tuning)" icon="sliders">
    ```lua theme={null}
    Tuning.Command = "remap"   -- comando que abre o menu

    Tuning.General = {
        accessMenuPerm = nil,            -- abrir menu (nil = todos)
        removeModulePerm = "Mechanic",   -- remover módulo
        installModulePerm = "Mechanic",  -- instalar módulo
        reqItemsToAccess = "",           -- item p/ abrir ("" = nenhum; apenas verifica, não consome)
        reqItemsToRemModule = "",
        reqItemsInstallModule = "",
        logo = "https://cdn.fivenetwork.dev/IDCore/LOGO%20-%20BRANCO.png",
        colors = { primaryColor = "#0095f3", secondaryColor = "#005c97", thirdyColor = "#003c61" },
    }

    Tuning.PopsAndBangs = { sound = true, particles = true }  -- particles=false usa partículas em rede (visíveis a todos)
    ```
  </Accordion>

  <Accordion title="Módulos (Tuning.Modules)" icon="gears">
    ```lua theme={null}
    Tuning.Modules = {
        ["suspensao"] = {
            name = "Suspensão a Ar",
            configItem = { necessaryToInstall = false, nameItem = "suspensaoar", animateTime = 5 },
            permToAccessMenu = {},  -- permissões p/ usar este módulo ({} = liberado)
        },
        -- neon, xenon, camber, offset, antiLag, remap, westgate, purgador (mesma estrutura)
    }
    ```

    * `necessaryToInstall = true` exige instalação física (item + animação); o item é **devolvido** ao remover.
    * A `key` do módulo (ex.: `"remap"`) é o identificador; `name` é só o rótulo.
  </Accordion>

  <Accordion title="Remap (handling) e outros" icon="gauge-high">
    ```lua theme={null}
    Tuning.RemapOptions = {
        { field = "fInitialDriveForce", key = "torque", title = "Torque", step = 0.01, var = 0.1 },
        { field = "fSteeringLock", key = "steering", title = "Ângulo", step = 1, var = 35 },
        -- fDriveInertia, fBrakeForce, fTractionCurveMax
    }
    Tuning.AntiLag = { periodMs = 350, randomMs = 350 }  -- cadência dos estouros
    Tuning.BlackListVehicles = { ["kuruma"] = true, ["t20"] = true }  -- modelos bloqueados (display name)
    ```
  </Accordion>
</AccordionGroup>

***

## Comandos

O recurso registra apenas um comando de chat.

| Comando  | Permissão                                                                              | Descrição                                                                                                                                                              |
| -------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/remap` | `Tuning.General.accessMenuPerm` (padrão `nil`, liberado a todos) via `Core.CheckPerms` | Abre o menu de tuning (nome em `Tuning.Command`). Valida permissão, blacklist (`Tuning.BlackListVehicles`), itens (`reqItemsToAccess`) e se está dentro de um veículo. |

<Note>
  Instalar/remover módulos não é comando: usa o evento `five-tuning:installModule` e o Tunnel `RemoveModule`, com as permissões `Tuning.General.installModulePerm` / `removeModulePerm` (padrão `"Mechanic"`).
</Note>

***

## Localizações

Não possui pontos fixos no mapa. O menu e a câmera orbital giram em torno do veículo do próprio jogador (offsets dinâmicos calculados em `client/core.lua` com `GetOffsetFromEntityInWorldCoords`), sem peds, blips, lojas ou zonas com coordenadas no config.

***

## Exports

Não declara exports Lua, usa **Tunnel** `five-tuning`:

* **Servidor→Cliente:** `OpenMenu`, `InstallModule`, `GetNearestVehicle`, `VehList`.
* **Cliente→Servidor:** `Save`, `CheckVehicleInfos`, `RemoveModule`, `CheckPerms`.

Evento de rede: `five-tuning:installModule` (instala módulo no veículo próximo).

***

## Banco de Dados

**Não cria tabela própria**: usa a tabela chave-valor `entitydata` do vRP. Chave: `zoCustomVehicle:<owner>veh_<modelo>placa_<placa>` (tuning amarrado a dono+modelo+placa). Valor: JSON com toda a config. Também cacheado no state bag do veículo (sincroniza visual entre jogadores).

<Warning>
  Exige placa com dono cadastrado (`vRP.PassportPlate`); veículos sem dono não salvam tuning.
</Warning>

***

## Customização

* **Módulos:** `Tuning.Modules` (novos módulos exigem entrada em `animationsParts` no client se forem instalação física).
* **Permissões/itens:** `Tuning.General` + `permToAccessMenu` por módulo (itens são verificados, não consumidos; item do módulo é devolvido ao remover).
* **Performance:** `Tuning.RemapOptions` (campos de `CHandlingData`).
* **Aparência:** `Tuning.General.logo`/`colors`.
* **Sons/backfire:** `Tuning.PopsAndBangs` + tabelas de som em `client/core.lua`.
* **Bloquear veículos:** `Tuning.BlackListVehicles`.

<Tip>
  Ajuste `Tuning.General.colors` e `logo` para alinhar a interface à identidade visual do seu servidor.
</Tip>