> ## 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-vehicles
> Sistema completo de veículos da Five Network: concessionárias, garagens, aluguel, mecânicas/tunagem, IPVA, apreensão, empréstimo e venda de veículos entre jogadores.
O **five-vehicles** é o recurso central de veículos do servidor. Ele controla todo o ciclo de vida de um veículo: compra/aluguel em concessionárias, guarda e retirada em garagens (públicas, de facção/serviço, aéreas e aquáticas), aplicação e cobrança de modificações nas mecânicas, sistema de IPVA, status especiais (apreendido, furtado, desmanchado) e ferramentas administrativas para gerar, renovar e remover veículos de personagens.
O cadastro de veículos (a `vehlist`) e a maioria das garagens são gerenciados em tempo real (em jogo) pelos comandos de administração, persistidos em banco de dados e sincronizados com os clientes via StateBag, não exigindo reinício do recurso. A UI é uma aplicação React (NUI) em `web-side/`.
## Funcionalidades
Compra, test drive e revenda de veículos com estoque configurável e descontos por permissão.
Guarda e retirada em garagens públicas, de facção/serviço, aéreas e aquáticas.
Frotas fixas de serviço com placas permanentes e empréstimo de chave.
Aplicação e cobrança de modificações (desativada quando o `five-bennys` está iniciado).
Imposto periódico calculado sobre o preço do veículo.
Apreendido, furtado e desmanchado, com multas associadas.
Sistema opcional de venda de veículos entre personagens.
CRUD de veículos e garagens via comandos de admin, persistido e sincronizado por StateBag.
A mecânica deste recurso é automaticamente **desativada** quando o recurso `five-bennys` está iniciado.
***
## Dependências
Declaradas no `fxmanifest.lua`.
Framework base (`@vrp/lib/utils.lua`, `@vrp/config/Global.lua`).
Acesso ao banco de dados.
Dependências opcionais detectadas em runtime via `GetResourceState`:
* **five-bennys**: quando iniciado, desativa a mecânica interna.
* **five-bank**: checagem de impostos/multas antes de retirar veículos.
* **core\_logs**: logs de compra/venda/aluguel.
* **propertys**: garagens vinculadas a casas.
***
## Configuração
```lua theme={null}
vehiclesVerbose = false -- mensagens de inicialização no console (debug)
ThemeColor = "#0143bb" -- cor da UI (Theme.main em Global.lua tem prioridade)
debugMode = false -- mensagens de debug no client
fixed_rental_plates = true
-- Gera placas PERMANENTES para veículos de serviço/aluguel (garagens 'SERVICE').
-- Permite salvar tunagem e porta-malas entre as retiradas. Se false, placa aleatória a cada retirada.
vehMenu = { enabled = true, key = 'M' } -- menu de veículos (segure M)
autoLockAIVehicles = true -- impede o uso de veículos de NPC (ficam trancados)
```
Cada comando tem `enabled`, `name` e `permission` (qualquer permissão da tabela libera).
```lua theme={null}
commands = {
['spawnVehicles'] = { enabled = true, name = 'car', permission = {'Admin'} },
['despawnVehicles'] = { enabled = true, name = 'dv', permission = {'Admin','Militar','Civil','CORE','BOPE','PRF'} },
['despawnAreaVehicles'] = { enabled = true, name = 'dvarea', maxRadius = 100, permission = {'Admin'} },
['fixVehicles'] = { enabled = true, name = 'fixar', permission = {'Admin'} },
['stockManager'] = { enabled = true, name = 'vstock', permission = {'Admin'} },
['characterVehManager'] = { enabled = true, name = 'vmanager', permission = {'Admin'} },
['garageManager'] = { enabled = true, name = 'gmanager', permission = {'Admin'} },
}
```
```lua theme={null}
vehicleTaxes = {
durationInDays = 7, -- a cada quantos dias o IPVA vence
percentFromPrice = 0.05 -- valor do IPVA = 5% do preço do veículo
}
borrowSystem = { enabled = false, ... } -- empréstimo de chave pela garagem
sellSystem = { enabled = false, ... } -- venda de veículos entre personagens
logsWebhooks = { ... } -- webhook do Discord por tipo de log (vazio = sem log)
```
```lua theme={null}
testDrive = {
payment = 200, -- valor do test drive (0 = grátis)
coords = {-1700.43,-2934.25,13.95,239.57}, -- teleporte do test drive
time = 120, -- tempo limite (segundos)
plate = 'PDMSPORT'
}
infiniteStock = true -- true: estoque infinito | false: usa five_vehicles_stock e /vstock
permissionDiscounts = { ['owner'] = 50 } -- desconto por permissão (%) na compra
sellBack = { enabled = true, percentFromPrice = 0.2, ... } -- revenda à concessionária (20%)
```
Cada concessionária é um bloco em `dealerships` com `coords`, `permission` (nil = livre), `blips`, `modelViewer` (ped + veículo exibido) e `disabledCategories`. Duplique o bloco para criar mais.
`garages_types` define quais categorias aparecem em cada tipo de garagem (`NORMAL`, `PROPERTY`, `AIR`, `WATER`). Cada garagem em `garages`:
```lua theme={null}
{
name = 'Garagem',
permission = nil, -- string, tabela {'p1','p2'} ou nil (pública)
payment = 500, -- (opcional) taxa de retirada; 0/ausente = grátis
type = 'NORMAL', -- NORMAL | PROPERTY | AIR | WATER | SERVICE
open = {101.04,-1073.62,29.38,261.67}, -- ponto de acesso
spawns = { {105.07,-1077.14,29.2,339.59} }, -- vagas de spawn
blip = { enabled = true, icon = 357, color = 0, size = 0.5 },
marker = { icon = 36, color = {255,255,255,255}, size = 0.8 }
}
```
Garagens de serviço/aluguel usam `type = 'SERVICE'` + `vehicles = { ['index'] = preço }` (frota fixa).
A mecânica só funciona se o `five-bennys` NÃO estiver iniciado. `DefaultTunnings` é a tabela de preços (cores, luzes, performance, rodas, insulfilm, etc.). Cada mecânica em `mechanics`:
```lua theme={null}
['mechanicName'] = {
coords = { {48.39,-878.02,30.37,151.54} },
blips = { enabled = true, id = 523, color = 61, size = 0.55, name = 'Mecânica' },
autoMode = true, -- sistema de pedidos/orçamento
permission = 'Ballas', -- permissão dos mecânicos
disablePerfTunnings = false,
onlyPerfTunnings = false,
tunnings = DefaultTunnings,
}
```
Define apenas as `categories` (chave => rótulo). A `vehlist` é **dinâmica** (gerenciada por `/gmanager`, persistida em `five_vehicles_registered`).
```js theme={null}
window.VEHICLE_IMAGE_URL = "https://pub-645a02b858fe4d66bc9365f1de3ee401.r2.dev/Cars";
// URL base das imagens: {URL}/{index}.png. Troque pela sua CDN.
```
***
## Comandos
Os comandos administrativos abaixo são definidos em `config/commands.lua`.
| Comando | Permissão | Descrição |
| --------------------- | --------------------- | ------------------------------------------- |
| `/car ` | Admin | Spawna um veículo pelo index do modelo. |
| `/dv` | Admin e forças | Remove o veículo mais próximo. |
| `/dvarea` | Admin | Remove veículos numa área (raio \~50). |
| `/fixar` | Admin | Conserta o veículo. |
| `/vstock` | Admin | Gerenciador de estoque das concessionárias. |
| `/vmanager ` | Admin | Gerenciador de veículos do personagem. |
| `/gmanager` | Admin | CRUD de garagens e de veículos (`vehlist`). |
| `/pedidos ` | permissão da mecânica | Mecânico atende pedidos de tunagem. |
Keybinds: trancar/destrancar veículo = `L` (remapeável); menu do veículo = `M` (`general.lua`).
***
## Localizações
Coordenadas reais usadas no config (formato `{x, y, z, heading}`). As garagens dinâmicas criadas por `/gmanager` ficam em `five_vehicles_garages` (banco) e não aparecem aqui.
### Test drive, concessionária e mecânica
| Local | Coordenadas | Tipo |
| --------------------------------------------------------------------- | --------------------------------- | ---------------------------------------- |
| Teleporte do test drive (`config/dealership.lua`, `testDrive.coords`) | -1700.43, -2934.25, 13.95, 239.57 | Ponto de spawn (test drive) |
| Concessionária / PDM: acesso (`dealerships[1].coords`) | -784.07, -212.87, 37.0, 303.31 | Loja (concessionária), blip desabilitado |
| Concessionária / PDM: ped do visualizador (`modelViewer.ped`) | -798.02, -221.4, 37.04, 297.64 | Ped |
| Concessionária / PDM: veículo do visualizador (`modelViewer.vehicle`) | -793.49, -218.14, 37.15, 119.06 | Spawn de veículo (exibição) |
| Mecânica `mechanicName` (`config/mechanics.lua`, `coords`) | 48.39, -878.02, 30.37, 151.54 | Mecânica (blip ativo, "Mecânica") |
### Garagens (`config/garages.lua`, tabela `garages`)
São 60 garagens ativas no config (campo `open` = ponto de acesso; cada uma tem `spawns` próprios). As de facção/órgão usam `blip = false`; várias garagens públicas têm blip (icon 357). Pontos de acesso (`open`):
| Local | Coordenadas (open) | Tipo |
| ----------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------- |
| Favela Fallet (pública) | -1394.36, 1558.04, 132.46, 85.04 | Garagem NORMAL (blip) |
| Hospital Norte (pública) | 1732.55, 3585.16, 35.18, 303.31 | Garagem NORMAL |
| Hospital Norte (serviço, `HospitalNorte`) | 1718.77, 3619.77, 34.58, 308.98 | Garagem SERVICE |
| Hospital Norte aérea (pública) | 1784.6, 3660.1, 39.85, 215.44 | Garagem AIR |
| Hospital Norte aérea (serviço, `HospitalNorte`) | 1777.3, 3655.48, 39.85, 300.48 | Garagem SERVICE/AIR |
| Hospital Sul (pública) | -1042.94, -392.26, 37.78, 34.02 | Garagem NORMAL |
| Hospital Sul (serviço, `HospitalSul`) | -1019.07, -415.63, 33.31, 28.35 | Garagem SERVICE |
| Hospital Sul aérea (pública) | -1005.29, -426.54, 78.28, 204.1 | Garagem AIR |
| Hospital Sul aérea (serviço, `HospitalSul`) | -1000.78, -424.49, 78.28, 209.77 | Garagem SERVICE/AIR |
| Polícia Militar (pública) | 2562.2, -339.57, 93.11, 5.67 | Garagem NORMAL |
| Polícia Militar (serviço, `Militar`) | 2563.47, -318.98, 92.99, 277.8 | Garagem SERVICE |
| Polícia Militar aérea (pública) | 2464.11, -391.25, 95.0, 170.08 | Garagem AIR |
| Polícia Militar aérea (serviço, `Militar`) | 2467.63, -390.89, 95.0, 170.08 | Garagem SERVICE/AIR |
| Polícia Civil (pública) | -1075.96, -1983.36, 13.16, 235.28 | Garagem NORMAL |
| Polícia Civil (serviço, `Civil`) | -1008.0, -2052.97, 13.31, 42.52 | Garagem SERVICE |
| Polícia Civil aérea (pública) | -989.6, -1999.42, 44.7, 42.52 | Garagem AIR |
| Polícia Civil aérea (serviço, `Civil`) | -985.96, -1996.07, 44.7, 45.36 | Garagem SERVICE/AIR |
| Polícia Civil aérea 2 (pública) | -1018.37, -1963.23, 44.7, 226.78 | Garagem AIR |
| Polícia Civil aérea 2 (serviço, `Civil`) | -1021.54, -1966.62, 44.7, 45.36 | Garagem SERVICE/AIR |
| BOPE (pública) | -1618.18, 165.45, 60.36, 297.64 | Garagem NORMAL |
| BOPE aérea (pública) | -1582.95, 206.55, 76.31, 291.97 | Garagem AIR |
| Maldivas Performance (pública) | 848.72, -904.4, 25.24, 272.13 | Garagem NORMAL |
| Maldivas Performance 2º andar (pública) | 818.99, -918.67, 43.15, 0.0 | Garagem NORMAL |
| Maldivas Performance (serviço, `MaldivasPerformance`) | 846.64, -925.02, 26.52, 272.13 | Garagem SERVICE |
| Maldivas Performance aérea (pública) | 825.12, -900.92, 52.42, 0.0 | Garagem AIR |
| Maldivas Performance aérea (serviço, `MaldivasPerformance`) | 821.61, -900.85, 52.42, 178.59 | Garagem SERVICE/AIR |
| Pública Aeroporto | -1022.9, -2735.68, 13.75, 328.82 | Garagem NORMAL (blip) |
| Pública (interior) | 101.04, -1073.62, 29.38, 261.67 | Garagem NORMAL (blip, `interiorExit` 108.67, -1071.33, 29.2, 64.82) |
| Pública | 412.74, -633.93, 28.51, 1.67 | Garagem NORMAL (blip) |
| Pública | 55.84, -876.32, 30.67, 76.38 | Garagem NORMAL (blip) |
| Pública | 597.09, 91.18, 93.13, 68.77 | Garagem NORMAL (blip) |
| Pública | -73.43, -2004.1, 18.28, 225.46 | Garagem NORMAL (blip) |
| Pública | -2030.59, -465.42, 11.61, 138.78 | Garagem NORMAL (blip) |
| Pública | -340.77, 266.61, 85.68, 187.69 | Garagem NORMAL (blip) |
| Pública | 1036.2, -763.2, 58.0, 231.01 | Garagem NORMAL (blip) |
| Pública (duplicada) | 1036.2, -763.2, 58.0, 231.01 | Garagem NORMAL (blip) |
| Pública | 317.12, 2622.99, 44.46, 307.34 | Garagem NORMAL (blip) |
| Pública | -773.18, 5597.72, 33.61, 174.52 | Garagem NORMAL (blip) |
| Pública | -389.15, 1186.8, 325.65, 174.36 | Garagem NORMAL (blip) |
| Pública | -317.25, -1512.75, 27.75, 174.53 | Garagem NORMAL (blip) |
| Pública | 2560.0, -370.5, 93.08, 181.67 | Garagem NORMAL (blip) |
| Pública | -1184.63, -1509.94, 4.65, 302.06 | Garagem NORMAL (blip) |
| Pública | -577.09, -1095.51, 22.18, 103.07 | Garagem NORMAL (blip) |
| Facção Triade | 379.63, -9.73, 82.99, 34.02 | Garagem NORMAL (sem blip) |
| Facção Fazenda | 1403.33, 1122.76, 114.83, 184.26 | Garagem NORMAL (sem blip) |
| Facção Jetsam | 819.38, -2967.3, 1.79, 175.75 | Garagem NORMAL (sem blip) |
| Facção Sinaloa | -1807.26, 410.89, 113.64, 238.12 | Garagem NORMAL (sem blip) |
| Facção Globo | -3673.31, 3817.52, 14.76, 243.78 | Garagem NORMAL (sem blip) |
| Facção Vinhedo | -1902.87, 2018.47, 140.88, 269.3 | Garagem NORMAL (sem blip) |
| Facção Playboy | -1534.49, 88.53, 56.77, 269.3 | Garagem NORMAL (sem blip) |
| Facção Casablanca | -1541.56, 841.34, 184.39, 351.5 | Garagem NORMAL (sem blip) |
| Facção Yakuza | -2333.51, -596.7, 13.58, 226.78 | Garagem NORMAL (sem blip) |
| Facção Distrito 14 | -678.25, 2699.2, 50.09, 314.65 | Garagem NORMAL (sem blip) |
| Facção Resort | -3022.47, 89.46, 11.61, 320.32 | Garagem NORMAL (sem blip) |
| Facção Posto | -2074.2, -322.4, 13.31, 79.38 | Garagem NORMAL (sem blip) |
| Facção Igreja | -328.78, 6145.9, 31.49, 138.9 | Garagem NORMAL (sem blip) |
| Facção Jack Of Hearts | 362.3, 298.34, 103.68, 340.16 | Garagem NORMAL (sem blip) |
| Facção Haute | -61.93, 220.69, 106.56, 274.97 | Garagem NORMAL (sem blip) |
| Facção Vanilla Sul | -670.32, -709.09, 24.67, 36.86 | Garagem NORMAL (sem blip) |
| Facção Vanilla Norte | -292.99, 6253.51, 31.44, 229.61 | Garagem NORMAL (sem blip) |
| Facção Yellow Jack | 1986.23, 3058.66, 47.21, 331.66 | Garagem NORMAL (sem blip) |
| Facção Racha Cranios | 1226.09, -3227.89, 6.03, 8.51 | Garagem NORMAL (sem blip) |
| Facção Mansao Black | -2784.65, 1414.92, 100.96, 56.7 | Garagem NORMAL (sem blip) |
| Facção Rising Sun | -376.99, -149.23, 38.7, 300.48 | Garagem NORMAL (sem blip) |
| Facção Favela Barragem | 1235.98, -4.94, 77.68, 82.21 | Garagem NORMAL (sem blip) |
| Facção Favela Demonike | -414.38, 1595.95, 360.59, 311.82 | Garagem NORMAL (sem blip) |
| Facção Favela Helipa | 1329.84, -770.0, 79.01, 283.47 | Garagem NORMAL (sem blip) |
| Facção Favela Juramento | -2094.17, 931.09, 204.41, 331.66 | Garagem NORMAL (sem blip) |
| Facção Favela Sinaloa | 1571.6, -1379.48, 84.79, 110.56 | Garagem NORMAL (sem blip) |
| Facção Favela Mare | -2496.19, -172.0, 45.21, 320.32 | Garagem NORMAL (sem blip) |
| Facção Favela MMDG | -837.73, 968.18, 250.81, 8.51 | Garagem NORMAL (sem blip) |
| Facção Favela Vaticano | 2629.34, 1829.97, 36.97, 192.76 | Garagem NORMAL (sem blip) |
| Facção Favela Santo Amaro | -1160.96, 2520.26, 41.5, 201.26 | Garagem NORMAL (sem blip) |
| Soda Pop (pública) | -1396.18, -1385.2, 3.64, 59.53 | Garagem NORMAL (sem blip) |
| Soda Pop (serviço, `SodaPop`) | -1398.92, -1396.24, 3.56, 96.38 | Garagem SERVICE |
| Moo Moo (pública) | -577.64, -1101.11, 22.38, 266.46 | Garagem NORMAL (sem blip) |
| Moo Moo (serviço, `MooMoo`) | -614.16, -1053.81, 21.79, 116.23 | Garagem SERVICE |
| Osaka Sushi (pública) | -768.65, -142.37, 37.73, 294.81 | Garagem NORMAL (sem blip) |
| Mariana/Marina Lounge (pública) | 1521.43, 3770.71, 34.19, 226.78 | Garagem NORMAL (sem blip) |
| Marina Lounge (serviço, `MarinaLounge`) | 1555.32, 3792.19, 34.26, 204.1 | Garagem SERVICE |
Os blocos de teste drive/garagens de exemplo no comentário do topo do arquivo (ex.: `{1297.75,-3344.01,...}`) e as garagens comentadas (BOPE exclusiva, Osaka serviço, Kitty Café) não estão ativos.
***
## Exports
O recurso expõe dezenas de exports server-side, entre eles:
* **Consulta:** `getVehicleInfo(hashOrIndex)`, `getVehicleList()`, `getVehicleIdentity(plate)`, `getVehicleData(plate)`, `getCharacterVehicles(characterId, includeBorrowed)`.
* **Criação:** `generateVehicle(characterId, model, customColors, customPlate)`, `giveVehicle(characterId, model)` (retorna `{ok, plate|error}`), `generateRentalVehicle(...)`.
* **Manutenção:** `updateRentalVehicleDays`, `updateVehicleTax`, `updateVehicleStatus`, `updateVehicleMods`, `changeVehiclePlateIRT`, `transferVehicle`, `deleteVehicle`.
* **Garagens:** `insertGarage(garage)`, `removeGarage(gId)`.
Client: `getVehicleInfo`, `getVehicleList`, `renderGarage`, `unrenderGarage`.
***
## Eventos
* `five-vehicles:vehicleCreated` (server): disparado quando um veículo é criado. Args: `plate, netId`.
* Eventos de compatibilidade com a antiga API "garages": `garages:Key`, `garages:Delete`, `garages:ChangePlate`, etc.
As ações de gameplay (comprar, alugar, guardar/retirar, tunar) são chamadas via **Tunnel** (tabela `SV`), não por net events públicos.
***
## Banco de Dados
As tabelas abaixo são criadas automaticamente na inicialização.
| Tabela | Conteúdo |
| ------------------------------- | ---------------------------------------------------------------------------- |
| `five_characters_vehicles` | Veículos dos personagens (placa, dono, status, IPVA, vida, mods). Principal. |
| `five_characters_vehicles_srvc` | Placas fixas de veículos de serviço/aluguel. |
| `five_vehicles_stock` | Estoque das concessionárias (`infiniteStock = false`). |
| `five_vehicles_borrowed` | Chaves emprestadas. |
| `five_vehicles_registered` | Cadastro dinâmico de veículos (a `vehlist`), via `/gmanager`. |
| `five_vehicles_garages` | Garagens dinâmicas, via `/gmanager`. |
***
## Customização
### Adicionar/editar veículos (vehlist)
Não edite `config/vehicles.lua` manualmente, use **`/gmanager`** (aba Veículos) em jogo. Campos persistidos: `spawn` (index, único), `name`, `category`, `paymentType` (`primary`/`secondary`=diamantes), `price`, `gemstone`, `weightTrunk`/`weightGloves`, `class`, `mode`, `outDealership`. As imagens vêm de `config.ui.js` → `{VEHICLE_IMAGE_URL}/{spawn}.png`.
### Adicionar concessionárias / garagens / mecânicas
* **Concessionárias:** duplique um bloco em `dealerships` (config/dealership.lua).
* **Garagens:** bloco estático em `garages` ou (recomendado) `/gmanager` em jogo.
* **Mecânicas:** entradas em `mechanics` (config/mechanics.lua). Lembre: `five-bennys` ativo desativa a mecânica interna.
### Limites de veículos por jogador
Hardcoded em `server-side/framework.lua` (`permissionLimits`): padrão 10; `vip1`=20, `vip2`=30, `vip3`=40, `admin`=50.
### Multas por status (server-side/framework.lua)
Apreendido = 25% do preço, furtado = 10%, desmanchado = 30%, IPVA atrasado = `vehicleTaxes.percentFromPrice`.
Prefira gerenciar veículos e garagens em jogo via `/gmanager`, evitando reinício do recurso.