qbx_mechanicjob — Manual

Emprego de mecânico da Autocare: registra o desgaste de peças dos veículos conforme a quilometragem rodada e permite consertá-las peça a peça, com o carro preso a uma plataforma da oficina.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Sistema de peças e desgaste
5. A oficina
6. Comandos
7. Integrações
8. Entrypoints para outros recursos
9. Localização
10. Estrutura de arquivos

Dependências

Instalação

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

   ensure qbx_mechanicjob
3. Cadastre o job mechanic (tipo mechanic) no qbx_core. O baú e os pontos da oficina exigem job.type == 'mechanic' e o jogador em serviço.
4. Garanta que os itens de reparo existam no ox_inventory: metalscrap, plastic, steel, aluminum, copper, iron e advancedrepairkit.
5. Preencha authorizedIds em config/server.lua com os citizenid dos donos da oficina — sem isso, /setmechanic e /firemechanic não funcionam para ninguém.
6. Conflitos — o fxmanifest.lua declara provide 'qb-mechanicjob'. Não rode junto com o qb-mechanicjob ou o qb-vehicletuning: os eventos qb-vehicletuning:* e vehiclemod:* são os mesmos.

A tabela player_vehicles do qbx_core já traz as colunas usadas (status, mods, drivingdistance) — não há SQL próprio.

Configuração

config/shared.lua

repairCost e repairCostAmount são tabelas independentes e, no config padrão, divergem (ex.: radiator mostra plastic no chat mas consome steel). Se ajustar uma, ajuste a outra.

Formato de uma plataforma (plates)

{
    coords = vec4(-340.95, -128.24, 39, 160.0),
    boxData = { heading = 340, length = 5, width = 2.5, debugPoly = false },
    AttachedVehicle = nil,
}

config/client.lua

Formato de minimalMetersForDamage

{ min = 8000, max = 12000, multiplier = { min = 1, max = 8 } }

Se a quilometragem (km) do veículo estiver entre min e max, o desgaste por tick é math.random(multiplier.min, multiplier.max) / 100 em cada peça de damageableParts. Acima da última faixa, o último multiplicador é usado.

config/server.lua

Sistema de peças e desgaste

Cada placa tem um estado de 7 peças: engine, body, radiator, axle, brakes, clutch, fuel. engine e body acompanham a saúde nativa do veículo; as outras cinco são gerenciadas pelo recurso e persistidas na coluna status de player_vehicles.

Desgaste por quilometragem (client/drivingdistance.lua): enquanto o jogador dirige, a distância percorrida é acumulada e enviada ao servidor a cada ~2 segundos. Se a quilometragem cair numa das faixas de minimalMetersForDamage, há 1 chance em 3, por tick, de desgastar as peças de damageableParts. Veículos que não estão no banco começam com uma quilometragem aleatória entre 111.111 e 999.999.

Efeitos do dano (client/damage-effects.lua): a cada 10–15 ticks dirigindo, um efeito é sorteado entre as peças abaixo de 80% de vida. Quanto pior a peça, mais severo o efeito. Veículos das classes 13, 14, 15, 16 e 21 (bicicletas, aviões, helicópteros, barcos, trens) são ignorados.

A oficina

Com o job mechanic e em serviço:

• Ponto de serviço — entra/sai de serviço (QBCore:ToggleDuty).
• Baú — abre a stash mechanicstash (500 slots, 4.000.000 de peso), restrita ao grupo mechanic.
• Garagem — na zona de veículos, abre a lista de veículos de trabalho (Flatbed, Towtruck, Minivan, Blista). Se já estiver dentro de um veículo, a mesma tecla o guarda. O veículo spawnado recebe placa MECH#### e tanque cheio.
• Plataforma — dirigindo até uma das plataformas, E prende o veículo ao elevador. Com o veículo preso, E abre o menu:
  • Desconectar veículo — solta o veículo e coloca o mecânico ao volante.
  • Ver status — envia ao chat o relatório com o valor de cada peça e o item de reparo correspondente.
  • Peças do veículo — lista as peças, e reparar uma consome o item de repairCostAmount e roda um progresso de 5 a 10 segundos.

O estado das plataformas (AttachedVehicle) é sincronizado no servidor: todos os clientes veem o mesmo veículo preso.

Comandos

/setmechanic e /firemechanic não são restritos por ACE: qualquer um pode digitar, mas só executam se o citizenid do autor estiver em config/server.lua > authorizedIds.

Integrações

scully_emotemenu

O reparo de peças toca a emote mechanic durante a barra de progresso, e a cancela ao terminar ou desistir.

ox_inventory

O baú mechanicstash é registrado na inicialização do servidor com o grupo mechanic. Os materiais de reparo são consumidos no servidor via RemoveItem, após checagem de quantidade.

HUD (hud:client:UpdateDrivingMeters)

A quilometragem calculada (em km) é enviada por esse evento a cada atualização, para exibição no HUD.

Entrypoints para outros recursos

Exports de cliente

-- Estado completo das peças de uma placa
local status = exports.qbx_mechanicjob:GetVehicleStatusList(plate)
 
-- Valor de uma peça específica
local engine = exports.qbx_mechanicjob:GetVehicleStatus(plate, 'engine')
 
-- Define o valor de uma peça (propaga ao servidor)
exports.qbx_mechanicjob:SetVehicleStatus(plate, 'radiator', 100)

Eventos de servidor

-- Inicializa o status de uma placa (usa o status do banco, se houver)
TriggerServerEvent('vehiclemod:server:setupVehicleStatus', plate, engineHealth, bodyHealth)
 
-- Atualiza uma peça (com clamp no valor máximo)
TriggerServerEvent('vehiclemod:server:updatePart', plate, part, level)
 
-- Define uma peça sem clamp
TriggerServerEvent('qb-vehicletuning:server:SetPartLevel', plate, part, level)
 
-- Restaura todas as peças ao máximo
TriggerServerEvent('vehiclemod:server:fixEverything', plate)
 
-- Persiste o status atual em player_vehicles
TriggerServerEvent('vehiclemod:server:saveStatus', plate)
 
-- Salva os mods do veículo em player_vehicles
TriggerServerEvent('qb-vehicletuning:server:SaveVehicleProps', vehicleProps)
 
-- Atualiza a quilometragem
TriggerServerEvent('qb-vehicletuning:server:UpdateDrivingDistance', amount, plate)

Eventos de cliente

-- Repara tudo no veículo em que o jogador está (precisa ser o motorista)
TriggerClientEvent('vehiclemod:client:fixEverything', source)
 
-- Define o valor de uma peça no veículo em que o jogador está
TriggerClientEvent('vehiclemod:client:setPartLevel', source, part, level)
 
-- Sincroniza o status de uma placa
TriggerClientEvent('vehiclemod:client:setVehicleStatus', -1, plate, status)

Callbacks (lib.callback)

• qb-vehicletuning:server:GetDrivingDistances() — quilometragem de todas as placas conhecidas
• qb-vehicletuning:server:IsVehicleOwned(plate) — se a placa existe em player_vehicles
• qb-vehicletuning:server:GetAttachedVehicle() — estado das plataformas

Localização

Strings via ox_lib locale, em locales/:

cs, de, en, es, pt, pt-br, ro

setr ox:locale "pt-br"

Estrutura de arquivos

qbx_mechanicjob/
├── client/
│   ├── main.lua              — zonas da oficina, plataformas, menus, reparo de peças, blip, exports
│   ├── damage-effects.lua    — efeitos do desgaste (radiador, direção, freios, embreagem, vazamento)
│   └── drivingdistance.lua   — cálculo da quilometragem e desgaste progressivo das peças
├── server/
│   └── main.lua              — status das peças, persistência em player_vehicles, stash, spawn de veículos, comandos
├── config/
│   ├── client.lua            — target, veículos de trabalho, faixas de desgaste, peças danificáveis
│   ├── server.lua            — citizenids autorizados a contratar/demitir
│   └── shared.lua            — valores máximos, custos de reparo, plataformas e locais da oficina
├── locales/                  — cs, de, en, es, pt, pt-br, ro (.json)
└── fxmanifest.lua