pickle_prisons — Manual

Sistema prisional com múltiplas prisões, confisco de inventário, atividades de trabalho, lojas internas, itens coletáveis e fuga por túnel com sirene.

Sumário

1. Dependências
2. Instalação
3. Permissões
4. Configuração
5. Definição de uma prisão
6. Atividades
7. Lojas e coletáveis
8. Fuga (breakout)
9. Comandos
10. Banco de dados
11. Integrações
12. Entrypoints para outros recursos
13. Localização
14. Estrutura de arquivos

Dependências

Instalação

1. Copie a pasta pickle_prisons para resources/.

2. Importe _INSTALL/SQL/install.sql (cria a tabela pickle_prisons).

3. Adicione os itens ao seu inventário. Os arquivos prontos ficam em _INSTALL/Items/:

   • ox_inventory.lua — colar em ox_inventory/data/items.lua
   • qbcore.lua — colar em qb-core/shared/items.lua
   • esx_limit.sql / esx_weight.sql — para ESX

   Os itens são wood, metal, rope e shovel. As imagens não vêm no repositório.

4. Adicione ao server.cfg:

   ensure ox_lib
   ensure pickle_xp   # opcional
   ensure pickle_prisons

5. Ajuste config.lua — no mínimo Config.Language, Config.UseTarget e as coordenadas da prisão.

O config.lua do repositório vem com Config.Debug = true.

Permissões

Não usa ACE. As permissões são por job (com nível mínimo) e por grupo do framework, definidas em Config.Default.permissions e opcionalmente sobrescritas por prisão.

permissions = {
    jail = {
        jobs = { ["police"] = 0, ["corrections"] = 0 },  -- ["job"] = nível mínimo
        groups = { "admin", "god" }
    },
    -- unjail, alert...
}

Configuração

Arquivo: config.lua.

Definição de uma prisão

Cada entrada de Config.Prisons aceita:

Atividades

Uma atividade tem seções. O jogador fala com um NPC (ou marker) para iniciar, e o servidor sorteia ou avança para a próxima seção. Ao concluir uma seção, as recompensas dela são entregues e a próxima é escolhida.

O catálogo fica em Config.Activities. Cada seção tem label, rewards e uma função process(data) que roda no client, executa a animação/minigame e retorna true (concluiu) ou false (falhou).

As atividades que já vêm configuradas:

O posicionamento é feito em Config.Prisons[x].activities:

Formatos aceitos em rewards: {type = "item", name, amount}, {type = "cash", amount}, {type = "weapon", name, amount} e {type = "xp", name, amount} (só com Config.XPEnabled).

Lojas e coletáveis

Lojas (stores)

Um NPC vende itens do catalog. Cada item tem name, description, amount e required — a lista de itens ou dinheiro cobrados. O servidor revalida o required antes de entregar.

{
    name = "shovel",
    description = "Maybe I could use this to escape...",
    amount = 1,
    required = {
        {type = "item", name = "wood", amount = 1},
        {type = "item", name = "metal", amount = 1},
        {type = "item", name = "rope", amount = 1},
    }
}

As lojas padrão são a “Prison Commissary” (hambúrguer e água por dinheiro) e o “Prison Plug” (canivete e pá, pagos com wood, metal e rope).

Coletáveis (lootables)

Props no mundo que entregam itens e ficam em cooldown.

O cooldown é global (por coletável, não por jogador) e vive só em memória no servidor.

Fuga (breakout)

Configurada em Config.Breakout:

Fluxo: o preso com a pá interage no ponto breakout.start e passa por três skill checks. Se conseguir, o servidor consome os itens, abre o túnel para todos por Config.Breakout.time segundos e dispara a sirene. Quem entrar no túnel (breakout.enter) é solto — sem receber o inventário confiscado de volta — e sai pelo ponto breakout.leave até o breakout.finish.

Sair do raio da prisão sem estar em uma fuga devolve o jogador à cela, a menos que Config.EnableSneakout = true.

Comandos

Todos são registrados no servidor.

O tempo do /jail é decrementado de 1 em 1 a cada minuto, ou seja, o valor é em minutos.

Banco de dados

Tabela pickle_prisons, criada por _INSTALL/SQL/install.sql:

O tempo restante é gravado no playerDropped e no onResourceStop.

Integrações

pickle_xp

Com Config.XPEnabled = true, o recurso registra as categorias de Config.XPCategories no pickle_xp no start e passa a entregar recompensas do tipo xp. Para usar outro sistema de XP, edite bridge/xp/server.lua.

ox_inventory

Quando iniciado, é usado para confiscar e devolver o inventário preservando metadata. Sem ele, cai no inventário nativo do qb-core ou do es_extended.

ND_Police

Ao ser preso, o client dispara ND_Police:uncuffPed para remover as algemas do jogador. Se o ND_Police não estiver no servidor, o evento simplesmente não é ouvido.

Target (ox_target, qb-target, qtarget)

Com Config.UseTarget = true, as interações viram opções de third-eye. Cada um tem sua bridge em bridge/target/.

Entrypoints para outros recursos

O recurso não expõe exports. Estes são os eventos e callbacks públicos.

-- Prende um jogador. Passa pela mesma validação de permissão do /jail.
TriggerServerEvent('pickle_prisons:jailPlayer', target, minutos, prisonIndex)
 
-- Solta um jogador.
TriggerServerEvent('pickle_prisons:unjailPlayer', target)
 
-- Solta o próprio jogador SEM devolver o inventário (usado pela fuga).
TriggerServerEvent('pickle_prisons:breakout')
 
-- Abre o diálogo de prender (o servidor dispara isso no /jailmenu).
TriggerClientEvent('pickle_prisons:jailDialog', source)

Eventos que o client dispara localmente e que outros recursos podem escutar:

-- O jogador entrou na prisão.
AddEventHandler('pickle_prisons:enterPrison', function() end)
 
-- O jogador saiu da prisão (solto, fugiu ou passou do raio com sneakout).
AddEventHandler('pickle_prisons:leavePrison', function() end)

O tempo de pena também é gravado no metadata do jogador com a chave injail (em minutos), o que permite que HUDs e outros recursos leiam o estado sem falar com o pickle_prisons.

Localização

As strings ficam em locales/translations/, uma tabela Language["<codigo>"] por arquivo. Idiomas incluídos:

• de.lua — alemão
• en.lua — inglês
• et.lua — estoniano
• pt-br.lua — português do Brasil

O idioma ativo é escolhido pelo Config.Language (não pela convar ox:locale).

Atenção: os label das atividades, das lojas e dos coletáveis não passam pelo sistema de locale — eles são escritos direto no config.lua.

Estrutura de arquivos

pickle_prisons/
├── config.lua                        — prisões, atividades, fuga, permissões, uniforme
├── core/
│   ├── client.lua                    — sistema de interações (marker/target), props, blips, WarpPlayer
│   └── shared.lua                    — utilitários compartilhados
├── modules/
│   ├── prison/
│   │   ├── client.lua                — celas, uniforme, raio da prisão, sirene, fuga, diálogo de prender
│   │   └── server.lua                — comandos, confisco de inventário, timer da pena, MySQL, sirene
│   ├── activities/
│   │   ├── client.lua                — interações das atividades e execução das seções
│   │   └── server.lua                — sorteio de seções e entrega de recompensas
│   ├── stores/
│   │   ├── client.lua                — NPCs e menu das lojas
│   │   └── server.lua                — validação e transação
│   └── lootables/
│       ├── client.lua                — props coletáveis e estado de cooldown
│       └── server.lua                — coleta e regeneração
├── bridge/
│   ├── qb/                           — qb-core: identifier, dinheiro, metadata, permissões, inventário fallback
│   ├── esx/                          — es_extended
│   ├── custom/                       — base para escrever a sua
│   ├── inventory/ox_inventory/       — inventário com metadata
│   ├── target/                       — ox_target, qb-target, qtarget
│   └── xp/                           — pickle_xp
├── locales/
│   ├── locale.lua                    — função _L
│   └── translations/                 — de, en, et, pt-br
├── nui/
│   ├── index.html                    — player de áudio da sirene
│   └── assets/                       — siren.mp3 e end_siren.mp3
├── _INSTALL/
│   ├── SQL/install.sql               — tabela pickle_prisons
│   └── Items/                        — itens para ox_inventory, qbcore e ESX
└── fxmanifest.lua