Qbx Jewelery

Roubo à joalheria Vangelico: hackeia a caixa elétrica para destrancar a porta, quebra as vitrines com arma na mão e leva as joias, disparando alarme e alerta policial.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Fluxo do roubo
5. Integrações
6. Entrypoints para outros recursos
7. Localização
8. Estrutura de arquivos

Dependências

Instalação

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

   ensure qbx_jewelery

3. Cadastre no ox_doorlock a porta da joalheria com o nome definido em doorlock.name (padrão vangelico_jewellery). Sem essa porta cadastrada, o hack não destranca nada.
4. Garanta que os itens existam no ox_inventory:
   • Item do hack: electronickit
   • Recompensas: rolex, diamond_ring, goldchain, 10kgoldchain
5. Conflitos: não rode junto com outro roubo da Vangelico (ex.: o qb-jewelery original). Os dois usariam a mesma porta e as mesmas vitrines.

Configuração

config/client.lua

config/server.lua

config/shared.lua

Formato de uma vitrine

{coords = vec3(-626.83, -235.35, 38.05), isOpened = false, isBusy = false, rayFire = 'DES_Jewel_Cab3', heading = 36.17}

O config traz um conjunto alternativo de vitrines (K4AMBI) comentado no final do arquivo, para quem usa a MLO da K4MB1.

Fluxo do roubo

1. O jogador chega à caixa elétrica com um electronickit. O servidor valida o item, a distância (2m) e a quantidade de policiais em serviço.
2. O item é consumido (se loseItemOnUse) e o minigame do ultra-voltlab roda por um tempo sorteado entre hackTime.min e hackTime.max, com cena sincronizada de animação na caixa.
3. Sucesso destranca a porta via ox_doorlock. Falha ou timeout apenas libera a caixa para uma nova tentativa.
4. Dentro da loja, com uma arma permitida em mãos, o jogador quebra as vitrines. Cada quebra roda a animação, o efeito RayFire, a partícula e o som, sincronizados para todos os jogadores num raio de 20 metros.
5. Cada vitrine quebrada entrega joias aleatórias (o que não couber no inventário cai no chão) e pode deixar uma digital. A primeira vitrine quebrada dispara o alarme e o alerta policial.
6. Após timeOut ms do alarme, a porta é retrancada, as vitrines são restauradas e a joalheria fica disponível novamente.

O raio de 80 metros em torno da primeira vitrine controla a criação da caixa elétrica e a manutenção do estado visual das vitrines já quebradas.

Proteções do servidor

O servidor guarda uma sessão por jogador para o hack e para cada vitrine, e só aceita a conclusão dentro de uma janela de tempo:

Só o jogador que abriu a sessão pode concluí-la. Se ele desconectar, a caixa elétrica e a vitrine são liberadas na hora. O estado das vitrines é enviado ao jogador quando ele carrega o personagem (QBCore:Server:OnPlayerLoaded).

Integrações

ox_doorlock

A porta com o nome de doorlock.name é destrancada (state 0) no hack bem-sucedido e retrancada (state 1) quando o cooldown do alarme expira.

ultra-voltlab

O minigame do hack é chamado via TriggerEvent('ultra-voltlab', tempo, callback). O callback recebe result: 0 falha, 1 sucesso, 2 tempo esgotado, -1 erro.

qbx_policejob

Alerta enviado em police:server:policeAlert na primeira vitrine quebrada. Digitais deixadas via evidence:server:CreateFingerDrop.

qb-scoreboard

A joalheria é marcada como ocupada (SetActivityBusy 'jewellery', true) durante o alarme e liberada quando o cooldown expira.

Entrypoints para outros recursos

Callbacks (lib.callback) no servidor

-- Valida item, polícia e distância; consome o item e abre a sessão do hack
lib.callback('qbx_jewelery:callback:electricalbox', false, cb)

-- Valida arma, estado da vitrine e distância; abre a sessão da quebra
lib.callback('qbx_jewelery:callback:cabinet', false, cb, vitrineIndex)

Eventos de servidor

Só têm efeito dentro de uma sessão aberta pelo callback correspondente (ver Proteções do servidor).

TriggerServerEvent('qbx_jewelery:server:endcabinet')       -- conclui a quebra, entrega joias, dispara alarme
TriggerServerEvent('qbx_jewelery:server:succeshackdoor')   -- hack bem-sucedido: destranca a porta
TriggerServerEvent('qbx_jewelery:server:failedhackdoor')   -- hack falhou: libera a caixa elétrica

Eventos de cliente

TriggerClientEvent('qbx_jewelery:client:alarm', -1)                  -- inicia o alarme
TriggerClientEvent('qbx_jewelery:client:syncconfig', -1, vitrines)   -- sincroniza o estado das vitrines

Localização

Strings via ox_lib locale, em locales/:

cs, de, en, es, fr, ja, nl, pl, pt, pt-br, ro, tr

setr ox:locale "pt-br"

Estrutura de arquivos

qbx_jewelery/
├── client/
│   └── main.lua          # caixa elétrica, minigame do hack, quebra das vitrines (RayFire, partícula, som), alarme
├── server/
│   └── main.lua          # validações, sessões, consumo do item, doorlock, recompensas, alarme e cooldown
├── config/
│   ├── client.lua        # digital, target/drawtext, duração do alarme
│   ├── server.lua        # cooldown, polícia mínima, pool de joias, armas permitidas
│   └── shared.lua        # caixa elétrica, doorlock, lista das 20 vitrines
├── locales/              # traduções (.json)
└── fxmanifest.lua