qbx_customs — Manual

Oficina de customização de veículos por polyzone: performance, peças, pintura (incluindo Chameleon), neon, rodas e reparo, com câmera orbital e cobrança configurável. Fork do popcornrp-customs.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Zonas
5. Preços e cobrança
6. Menus
7. Persistência
8. Entrypoints para outros recursos
9. Localização
10. Estrutura de arquivos

Dependências

Instalação

1. Copie a pasta qbx_customs para resources/.
2. Adicione ao server.cfg:

   ensure qbx_customs
3. Configure as zonas em config/shared.lua. As coordenadas que vêm de fábrica são de mapas específicos (MRPD e Benny’s do Molo) e precisam ser ajustadas para o seu servidor.
4. A tabela player_vehicles (padrão do qbx_core) precisa existir. Não há SQL próprio.

Conflitos — substitui qualquer outro recurso de LS Customs / Benny’s (qb-customs, bennys, etc.). Rodar dois ao mesmo tempo gera zonas e menus duplicados.

O recurso registra carcols_gen9.meta e carmodcols_gen9.meta como data files, além de streamar vehicle_paint_ramps.ytd — necessários para as pinturas Chameleon.

Configuração

config/shared.lua

config/client.lua

Basicamente um catálogo de labels. Alterar aqui muda apenas o que aparece no menu — os IDs são os nativos do GTA V.

Zonas

Cada item de zones é uma polyzone definida por points. Todos os pontos devem ter o mesmo valor de Z — alturas diferentes quebram a zona.

O jogador precisa estar dentro do veículo e dentro da zona. Um TextUI aparece à direita; pressionar E (controle 38) zera a velocidade do carro, abre o menu e liga a câmera orbital.

As quatro zonas que vêm de fábrica (todas com hideBlip = true): LS Customs do centro, Hawick/La Mesa, Grapeseed e Paleto.

Preços e cobrança

O cliente pede o pagamento ao servidor antes de aplicar cada modificação. O servidor:

1. Consulta a zona atual do jogador (callback qbx_customs:client:zone).
2. Se o job do jogador está em freeMods (ou freeRepair, no caso do reparo) daquela zona, libera sem cobrar.
3. Caso contrário, tenta debitar de cash; se não houver saldo, debita de bank e notifica. Sem saldo em nenhum dos dois, a modificação é recusada.

Reparo — o preço é calculado dinamicamente: ceil(1000 - bodyHealth). Um carro intacto (1000 de body health) não mostra a opção de reparo; um destruído custa até $1000. O reparo restaura body e engine health, mantendo o nível de combustível.

Quando o veículo está danificado, o menu principal exibe apenas a opção de reparo — os menus de customização só liberam com o carro inteiro.

Menus

Durante o menu, os controles de acelerar, frear, virar as rodas e trocar de rádio ficam desabilitados. A câmera orbital (dragcam) é controlada pelo mouse, com zoom via scroll.

Persistência

Ao fechar o menu, o cliente dispara qbx_customs:server:saveVehicleProps. O servidor lê as propriedades do veículo, verifica se a placa existe em player_vehicles e, em caso positivo, atualiza a coluna mods:

UPDATE player_vehicles SET mods = ? WHERE plate = ?

Veículos que não estão no banco (spawnados por admin, NPC, etc.) são modificados mas não têm os mods salvos.

Entrypoints para outros recursos

Callback mri_Qbox:customs:client (cliente)

Abre o menu de customs no cliente sem passar pela zona. Usado por integrações da suite MRI (por exemplo, um ponto de target próprio).

lib.callback.await('mri_Qbox:customs:client', playerId)

Callback qbx_customs:client:zone (cliente)

Retorna o índice da zona em que o jogador está, ou nil.

local zoneId = lib.callback.await('qbx_customs:client:zone', playerId)

Callback qbx_customs:client:vehicleProps (cliente)

Retorna lib.getVehicleProperties do veículo atualmente no menu.

local props = lib.callback.await('qbx_customs:client:vehicleProps', playerId)

Callback qbx_customs:server:pay (servidor)

Cobra por um mod. mod é 'cosmetic', 'colors' ou o ID numérico (11, 12, 13, 15, 18); level é o nível instalado. Retorna true se pago (ou gratuito pelo job).

local paid = lib.callback.await('qbx_customs:server:pay', false, mod, level)

Callback qbx_customs:server:repair (servidor)

Cobra o reparo com base no bodyHealth atual. Retorna true se pago ou gratuito.

local paid = lib.callback.await('qbx_customs:server:repair', false, GetVehicleBodyHealth(vehicle))

Evento qbx_customs:server:saveVehicleProps

Salva os mods do veículo em player_vehicles, se a placa existir.

TriggerServerEvent('qbx_customs:server:saveVehicleProps')

Localização

Strings via ox_lib locale, em locales/:

de, en, fr, pt-br

Idioma ativo definido no server.cfg:

setr ox:locale "pt-br"

Estrutura de arquivos

qbx_customs/
├── client/
│   ├── menus/
│   │   ├── main.lua           — menu raiz, reparo, controle de câmera, save ao fechar
│   │   ├── performance.lua    — motor, freios, transmissão, suspensão, turbo
│   │   ├── parts.lua          — mods cosméticos
│   │   ├── colors.lua         — pintura, película, placa, fumaça de pneu
│   │   ├── paint.lua          — seleção de tinta por acabamento
│   │   ├── neon.lua           — posições e cores de neon
│   │   ├── wheels.lua         — tipos e modelos de roda
│   │   └── extras.lua         — extras do veículo
│   ├── enums/
│   │   ├── VehicleClass.lua   — enum de classes de veículo
│   │   └── WheelType.lua      — enum de tipos de roda
│   ├── dragcam.lua            — câmera orbital com mouse e zoom
│   ├── utils.lua              — GetModLabel, InstallMod (chama o pagamento)
│   └── zones.lua              — polyzones, blips, TextUI, callbacks de zona
├── server/
│   └── main.lua               — cobrança, reparo, save dos mods em player_vehicles
├── config/
│   ├── client.lua             — moeda, catálogo de mods, pinturas, neon, rodas
│   └── shared.lua             — debug, zonas e preços
├── locales/
│   └── *.json                 — traduções (4 idiomas)
├── stream/
│   └── vehicle_paint_ramps.ytd — texturas das pinturas Chameleon
├── carcols_gen9.meta          — definições de cores gen9
├── carmodcols_gen9.meta       — definições de cores dos mods gen9
├── types.lua                  — anotações LuaLS de ZoneOptions e blipOptions
└── fxmanifest.lua