randol_carheist — Manual

Roubo de carro sob encomenda: pegue o serviço com o NPC, invada a garagem marcada, despiste o rastreador da polícia por 5 minutos, entregue o veículo e troque os papéis por dinheiro.

Sumário

1. Dependências
2. Instalação
3. Item heist_papers
4. Configuração
5. Fluxo do roubo
6. Rastreador e polícia
7. Cooldown
8. Bridge de framework
9. Entrypoints para outros recursos
10. Estrutura de arquivos

Dependências

Instalação

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

   ensure randol_carheist
3. Cadastre o item heist_papers no seu inventário (ver seção abaixo) e copie image/heist_papers.png para a pasta de imagens do inventário.
4. Ajuste RequiredCops, Cooldown e a faixa de pagamento em sv_config.lua.

Item heist_papers

O recurso entrega o item heist_papers com metadata (amount, cid, description) no lugar de pagar direto. Só quem roubou o carro consegue trocar os papéis por dinheiro — o servidor compara o cid da metadata com o do jogador.

Para ox_inventory, em data/items.lua:

['heist_papers'] = {
    label = 'Vehicle Papers',
    weight = 0,
    stack = false,
    close = true,
    description = 'Delivery documents.',
    client = {
        image = 'heist_papers.png',
    }
},

Para qb-inventory, em shared/items.lua:

heist_papers = {
    name = 'heist_papers',
    label = 'Vehicle Papers',
    weight = 0,
    type = 'item',
    image = 'heist_papers.png',
    unique = true,
    useable = false,
    shouldClose = true,
    combinable = nil,
    description = 'Delivery documents.'
},

Configuração

Arquivo: sv_config.lua. O servidor envia a config inteira para os clientes ao iniciar o recurso e ao jogador logar (evento randol_carheist:cacheConfig).

Fluxo do roubo

1. O NPC (PedCoords) tem duas opções de target: Start Job e Return Papers.
2. Ao aceitar, o servidor sorteia modelo, garagem e ponto de entrega. Um blip de raio de 100 m marca a região da garagem — a posição exata não é revelada.
3. Chegando na garagem, a opção “Enter Garage” toca a animação de abrir o portão, escurece a tela e spawna o carro sorteado com o jogador já no banco do motorista. Placa CARH + 4 dígitos, cores aleatórias, tanque cheio.
4. O rastreador liga: por 5 minutos a polícia recebe a posição do carro a cada 5 segundos.
5. O ponto de entrega é marcado no GPS. A entrega só é aceita com o rastreador desligado.
6. Na zona de entrega, E inicia a descarga (3 s). O servidor confere que o jogador está a menos de 10 m do ponto, deleta o carro e entrega os heist_papers com o valor sorteado.
7. De volta ao NPC, “Return Papers” troca o item pelo dinheiro em espécie.

Se o jogador cair do servidor ou deslogar durante o serviço, o carro é deletado e o roubo é cancelado.

Rastreador e polícia

Enquanto o rastreador está ativo, o servidor chama PoliceTracker(coords) a cada 5 segundos, que envia randol_carheist:client:trackerUpdate para todos os policiais em serviço. Do lado deles, um blip pulsante “CAR HEIST” acompanha o carro.

O rastreador roda 60 ciclos de 5 segundos (5 minutos) e então dispara randol_carheist:client:trackerOff, avisando o ladrão de que está liberado para entregar. Se o carro deixar de existir antes disso, o serviço é cancelado.

A contagem de policiais (CheckCopCount) e o alerta inicial (AlertPolice) vêm da bridge. No QBCore, o alerta usa ps-dispatch.

Cooldown

Cooldown (em minutos) tem duas funções ao mesmo tempo:

• É o prazo do serviço. Quando expira, o roubo é resetado: o jogador recebe “You ran out of time, ditch the car” e o carro perde a utilidade (a entrega não é mais aceita).
• É o cooldown global do servidor. Enquanto ele estiver correndo, nenhum outro jogador consegue pegar o serviço (“Heist is on cooldown”).

Ou seja, apenas um roubo por vez roda no servidor, e o próximo só libera Cooldown minutos depois do anterior ter começado.

Bridge de framework

Cada arquivo em bridge/ só é carregado se o recurso correspondente estiver started:

Funções fornecidas pela bridge do servidor: GetPlayer, DoNotification, GetPlyIdentifier, GetSourceFromIdentifier, GetCharacterName, GetItemData, RemoveHeistPapers, AddHeistPapers, AddRewardMoney, CheckCopCount, PoliceTracker.

Funções da bridge do cliente: handleVehicleKeys, hasPlyLoaded, DoNotification e AlertPolice (opcional — só é chamada se estiver definida).

O bridge do QBCore detecta o ox_inventory automaticamente e usa GetSlotWithItem / AddItem com metadata; sem ele, cai no qb-inventory.

Entrypoints para outros recursos

Não há exports. Callbacks registrados no servidor:

-- Valida polícia e cooldown; sorteia modelo, garagem e entrega. Retorna a tabela do serviço ou false
lib.callback.await('randol_carheist:attemptjob', false)
 
-- Spawna o carro na garagem, liga o rastreador e alerta a polícia. Retorna o netId
lib.callback.await('randol_carheist:server:createVehicle', false)
 
-- Valida a distância da entrega (10 m), deleta o carro e entrega os heist_papers
lib.callback.await('randol_carheist:server:finishHeist', false, vehicleNetId)
 
-- Troca os heist_papers pelo dinheiro (valida o cid da metadata)
lib.callback.await('randol_carheist:server:returnPapers', false)

Eventos de cliente disparados pelo servidor (todos ignoram chamadas vindas de outros recursos):

Estrutura de arquivos

randol_carheist/
├── cl_carheist.lua       — NPC, blip de área, entrada da garagem, blips do rastreador, entrega
├── sv_carheist.lua       — sorteio do serviço, spawn do carro, rastreador, cooldown, papéis e pagamento
├── sv_config.lua         — polícia mínima, NPC, combustível, entregas, pagamento, carros, garagens
├── bridge/
│   ├── client/
│   │   ├── qb.lua        — QBCore: chaves, notificações, alerta ps-dispatch
│   │   ├── esx.lua       — ESX
│   │   └── nd.lua        — ND
│   └── server/
│       ├── qb.lua        — QBCore: player, inventário (ox/qb), contagem de policiais, tracker
│       ├── esx.lua       — ESX
│       └── nd.lua        — ND
├── image/
│   └── heist_papers.png  — ícone do item para o inventário
└── fxmanifest.lua