mri_QexoticPaints — Manual

Latas de spray usáveis que aplicam as cores exóticas (anodizadas, flip, pearl, prismáticas, holográficas) do game build 2699+ em veículos, com animação de pintura e persistência no banco.

Sumário

1. Dependências
2. Instalação
3. Itens
4. Como funciona
5. Cores disponíveis
6. Entrypoints para outros recursos
7. Estrutura de arquivos

Dependências

O recurso também exige game build 2699 ou superior. O client.lua verifica GetGameBuildNumber() na inicialização e aborta com a mensagem YOU NEED AT LEAST 2699 GAME BUILD se o build for menor.

Instalação

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

   ensure mri_QexoticPaints
3. Garanta que o servidor roda com build 2699+ (sv_enforceGameBuild 2699 ou superior).
4. Cadastre os itens de spray no inventário — um item por cor, com o nome exatamente igual à chave da tabela Paints em colors.lua. Veja Itens.
5. O recurso deve iniciar antes do jogador entrar no servidor: os arquivos meta/carcols_gen9.meta e meta/carmodcols_gen9.meta são registrados como data_file e precisam estar carregados para as cores existirem.

Itens

Cada cor é um item usável separado. O servidor registra todos automaticamente:

for i, d in pairs(Paints) do
    QBCore.Functions.CreateUseableItem(i, function(source, item)
        TriggerClientEvent("lambra-exoticPaints:client:usedSpray", source, i)
    end)
end

Ou seja, o nome do item precisa ser idêntico à chave da tabela Paints (anod_red, ykta_hsw, etc.). Se o item não existir no inventário, a lata simplesmente não pode ser usada.

Exemplo de item (formato qb-core/shared/items.lua):

['anod_red'] = { ['name'] = 'anod_red', ['label'] = 'Exotic Spray can', ['weight'] = 200, ['type'] = 'item', ['image'] = 'exoticspray.png', ['unique'] = false, ['useable'] = true, ['description'] = 'Anod Red' },

O item deve ser useable = true. A lista completa de nomes está em Cores disponíveis e o README.md do repositório traz o bloco pronto com as 81 entradas.

Como funciona

1. O jogador usa a lata de spray fora do veículo, a até 5 metros do carro.
2. O script pega o veículo mais próximo (GetClosestVehicle, raio 5.0), congela ele, e toca a animação de pintura com o prop prop_cs_spray_can na mão.
3. A carga da lata começa em 100% e é exibida em texto 3D acima do prop.
4. Segurando o botão de ataque (mouse esquerdo), o jogador pinta: a carga cai 3% por segundo e sai o efeito de partícula scr_lamgraff_paint_spray.
5. Ao soltar o botão, a lata precisa ser chacoalhada antes de pintar de novo — segure o botão de mira (mouse direito) para reproduzir a animação de agitar a lata.
6. Quando a carga chega a 0%, a pintura é aplicada: SetVehicleColours(veh, Paints[item], Paints[item]) define a cor primária e secundária.
7. O item é consumido no servidor (RemoveItem) e, se a placa existir em player_vehicles, as propriedades do veículo são gravadas na coluna mods.

Sair do raio de 5 metros do veículo cancela o processo: o prop é apagado, o veículo é descongelado e nada é aplicado nem consumido.

Cores disponíveis

A tabela Paints (em colors.lua) mapeia o nome do item para o índice de cor do GTA. É esse arquivo que você edita para adicionar ou remover cores.

Cores registradas (item → índice):

O índice 205 não é usado.

Entrypoints para outros recursos

Evento lambra-exoticPaints:client:usedSpray (cliente)

Inicia o modo de pintura no cliente. É o evento disparado pelo item usável, mas pode ser chamado por qualquer recurso do servidor.

TriggerClientEvent('lambra-exoticPaints:client:usedSpray', source, 'anod_red')

O parâmetro é a chave da tabela Paints. Se o jogador já estiver em modo de pintura, ou não houver veículo a menos de 5 metros, o evento é ignorado.

Evento lambra-exoticPaints:client:finishedSpray (servidor)

Apesar do nome, é um evento de servidor (RegisterNetEvent no server.lua). O cliente o dispara ao concluir a pintura; ele consome o item e persiste as mods do veículo em player_vehicles quando a placa é de um veículo registrado.

TriggerServerEvent('lambra-exoticPaints:client:finishedSpray', vehicleProps, 'anod_red')

Estrutura de arquivos

mri_QexoticPaints/
├── client.lua                    — modo de pintura: prop, animações, partículas, carga da lata, SetVehicleColours
├── server.lua                    — registra os itens usáveis, consome o item e grava as mods em player_vehicles
├── colors.lua                    — tabela Paints: nome do item → índice de cor (shared)
├── meta/
│   ├── carcols_gen9.meta         — definição das cores exóticas (data_file CARCOLS_GEN9_FILE)
│   └── carmodcols_gen9.meta      — definição das cores de mods (data_file CARMODCOLS_GEN9_FILE)
├── stream/
│   └── vehicle_paint_ramps.ytd   — texturas das rampas de cor
└── fxmanifest.lua