qbx_truckrobbery — Manual

Assalto a carro-forte em movimento: o jogador contrata a missão com um NPC, para o caminhão, planta um explosivo na porta traseira e saqueia a carga.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Fluxo da missão
5. Estados do caminhão
6. Recompensas
7. Integrações
8. Entrypoints para outros recursos
9. Localização
10. Estrutura de arquivos

Dependências

Instalação

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

   ensure qbx_truckrobbery
3. Garanta que os itens usados existem no ox_inventory:
   • WEAPON_STICKYBOMB — o explosivo consumido para abrir o caminhão (bombItem).
   • black_money e security_card_01 — recompensas padrão em config/server.lua.
4. Ajuste numRequiredPolice conforme o número mínimo de policiais em serviço que o servidor exige.

Configuração

config/shared.lua

config/client.lua

config/server.lua

Fluxo da missão

1. O jogador fala com o NPC (dealerCoords) e escolhe “pedir missão”. A opção não aparece para jobs do tipo leo.
2. O servidor valida: nenhuma missão ativa, saldo bancário >= activationCost, e policiais em serviço >= numRequiredPolice. O custo é debitado do banco.
3. Um dos truckSpawns é sorteado. O jogador recebe o e-mail de briefing e um blip de área de 250 m de raio, com rota.
4. Ao entrar na área, o caminhão é spawnado com 4 guardas armados. O blip vira um marcador piscante preso ao veículo, e o caminhão dirige erraticamente pela cidade.
5. Quando qualquer jogador chega a menos de 5 m do caminhão (e a bomba ainda não foi plantada), a polícia é alertada.
6. Com o caminhão parado e fora d’água, o jogador planta a bomba (barra de 5 s). O item é consumido no servidor.
7. Após timeToDetonation segundos, as portas traseiras explodem e o caminhão fica saqueável.
8. O saque leva lootDuration ms e afastar-se mais de 6 m cancela a ação. As recompensas são sorteadas e entregues.
9. A missão só volta a ficar disponível depois de missionCooldown.

Falha — se ninguém estiver perto do caminhão (ele deixa de ter dono de rede) e a bomba ainda não tiver sido plantada, o caminhão é deletado e a missão falha.

Qualquer jogador pode interagir com o caminhão, não só quem pagou a missão. Isso é intencional: permite que gangues rivais disputem a carga.

Estados do caminhão

O caminhão carrega o statebag truckstate, replicado para todos os clientes. Outros recursos podem ler Entity(truck).state.truckstate:

Os guardas usam o statebag qbx_truckrobbery:initGuard para que o cliente dono da entidade aplique os atributos de combate.

Recompensas

Definidas em config.rewards. Cada item é avaliado de forma independente:

rewards = {
    {
        item = 'black_money',
        minAmount = 250,
        maxAmount = 450,
    },
    {
        item = 'security_card_01',
        probability = 0.05
    }
}

Se o jogador não tiver espaço no inventário, os itens restantes viram um drop no chão (“Loot”) na posição dele.

Integrações

ox_inventory

O explosivo é validado no cliente (Search) e consumido no servidor (RemoveItem). Ao plantar, o recurso dispara ox_inventory:disarm para guardar a arma em mãos antes da animação. As recompensas usam AddItem, CanCarryItem e CustomDrop.

qb-phone

Duas funções do config assumem o qb-phone:

• emailNotification (client) — envia o e-mail de briefing via qb-phone:server:sendNewMail.
• alertPolice (server) — envia qb-phone:client:addPoliceAlert para os policiais em serviço.

Ambas são funções no arquivo de config; se o servidor usa outro telefone/dispatch, basta reescrever o corpo delas.

Polícia (leo)

Jobs com type = 'leo' não conseguem contratar a missão, plantar a bomba nem saquear o caminhão. A contagem de policiais em serviço usa exports.qbx_core:GetDutyCountType('leo'), tanto para o mínimo exigido quanto para o alerta.

Entrypoints para outros recursos

Não há exports. Os pontos de entrada são eventos e callbacks:

-- Servidor: inicia a missão para o jogador (mesma validação do NPC)
TriggerServerEvent('qbx_truckrobbery:server:startMission')
 
-- Cliente: avisado quando a missão começa (recebe as coords do spawn)
RegisterNetEvent('qbx_truckrobbery:client:missionStarted', function(vehicleSpawnCoords) end)
 
-- Cliente: avisado quando o cooldown termina e a missão é encerrada
RegisterNetEvent('qbx_truckrobbery:client:missionEnded', function() end)

Callbacks registrados no servidor:

• qbx_truckrobbery:server:spawnVehicle — spawna o caminhão e os guardas, devolve o netId.
• qbx_truckrobbery:server:giveReward — valida o estado lootable e entrega o loot.

Localização

Strings via locale do ox_lib. Idiomas em locales/: da, de, en, fr, pt, pt-br.

setr ox:locale "pt-br"

Estrutura de arquivos

qbx_truckrobbery/
├── client/
│   └── main.lua          — NPC contratante, blips, targets de plantar/saquear, handlers de statebag
├── server/
│   └── main.lua          — validação e cooldown da missão, spawn do caminhão e guardas, detonação, loot
├── shared/
│   └── types.lua         — enum TruckState (plantable, planted, lootable, looted)
├── config/
│   ├── client.lua        — NPC, blips, precisão dos guardas, duração do saque, e-mail de briefing
│   └── server.lua        — polícia mínima, custo, cooldown, loot, armas, modelos, spawns, alerta
├── locales/              — traduções (da, de, en, fr, pt, pt-br)
└── fxmanifest.lua