mri_Qpets — Manual

Sistema de pets (fork do keep-companion, do Swkeep) com item de invocação, fome, sede, vida, XP/nível, variações de cor, truques e uma unidade K9 para a polícia.

Sumário

1. Dependências
2. Instalação
3. Configuração
4. Pets disponíveis
5. Itens
6. Comandos
7. Menu do pet
8. Ciclo de vida do pet
9. Unidade K9
10. Variações de cor
11. Integrações
12. Entrypoints para outros recursos
13. Localização
14. Estrutura de arquivos

Dependências

Este é um fork com conversão parcial para OX: o ox_inventory substituiu o inventário do QB, mas o resto do código continua dependendo do qb-core.

Instalação

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

   ensure mri_Qpets
3. Cadastre os itens no ox_inventory — os 15 itens de pet (keepcompanion*) e os 6 itens de cuidado. Os nomes exatos estão em Itens. Os pets precisam ser stack = false (cada pet é único, identificado por um hash na metadata).
4. Copie as imagens de inventory_images/ para a pasta de imagens do seu inventário (22 PNGs: um por pet e um por item de cuidado).
5. Stream do modelo K9 — o modelo a_c_k9 é um ped addon e não é streamado por este recurso (o fxmanifest não declara files nem data_file). A pasta K9addon/ traz os arquivos prontos (data/peds.meta e stream/): mova-os para um recurso de stream próprio. Sem isso, o pet keepcompanionk9unit não spawna.
6. Adicione os pets e itens às lojas do seu servidor (ox_inventory shops ou qb-shops). O keepcompanionk9unit deve ficar em uma loja de acesso exclusivo da polícia.
7. Ajuste Config.inventory_name se o seu inventário de veículos não for o qb-inventory — o export de busca em porta-malas/porta-luvas do K9 depende disso.

Não há SQL a importar: todo o estado do pet é metadata do item no ox_inventory.

Configuração

Arquivo: config.lua

Geral

Config.Settings

Config.Balance

Config.pets

Lista de pets. Cada entrada:

Config.core_items

Não altere as chaves da tabela (food, collar, nametag, firstaid, groomingkit, waterbottle) — só o item_name e as settings.

As chaves usage_cycle, resting_cycle, overeat, max_overeat, weight_gain_by_evereat e max_weight_gain_by_evereat em food.settings são placeholders do autor original e não têm efeito no código.

Config.k9

Pets disponíveis

Todos são itens usáveis: o primeiro uso inicializa o pet (gera hash, nome, gênero, variação); os usos seguintes chamam ou guardam o pet.

Itens

O item water_bottle (água comum do servidor) precisa existir: é ele que enche a garrafa do pet.

Comandos

Todos são registrados via QBCore.Commands.Add com a permissão admin.

O menu do pet não tem comando: é aberto pela tecla mapeada em Config.Settings.petMenuKeybind (padrão o), registrada com RegisterKeyMapping. O menu não abre se o jogador estiver algemado, no menu de pausa, ou caído (a menos que seja polícia ou paramédico).

Menu do pet

Aberto pela tecla do keybind, exige pelo menos um pet ativo.

Ações

“Revistar pessoa” aparece no menu para todos, mas a função recusa quem não for police em serviço.

Truques

Implorar, Dar a pata e Fingir-se de morto.

Trocar de controle

Alterna qual pet ativo recebe os comandos do menu, quando MaxActivePetsPetPlayer for maior que 1.

Opções no ox_target (mirando o pet)

Ciclo de vida do pet

Todo o estado do pet fica na metadata do item no ox_inventory e é salvo pelo servidor a cada 5 segundos enquanto o pet está spawnado.

Vida ≤ 100 significa pet morto. É por isso que maxHealth na config nunca deve ser baixa: os 100 primeiros pontos de vida do GTA são a “faixa morta” e o script trata qualquer valor abaixo disso como zero.

Comida em 0 drena 0,2 de vida por ciclo; sede em 100 drena 0,5 por ciclo. Quando a vida chega em 100 por fome ou sede, o pet é morto à força (keep-companion:client:forceKill).

Se um jogador tentar usar um item de pet cujo owner.phone não bate com o dele, o pet é spawnado e imediatamente removido, e ele recebe a notificação “Você não é o dono deste pet”.

Unidade K9

O recurso tem duas ações de busca, ambas exigindo o job police em serviço:

• Revistar pessoa — o servidor varre o inventário do jogador mais próximo procurando os itens de Config.k9.illegal_items. Essa ação não checa o modelo do pet: qualquer pet de um policial em serviço pode fazê-la.
• Revistar carro — exclusiva do K9. O pet caminha até dois pontos do veículo (lateral e traseira) e checa porta-luvas e porta-malas via os exports getGloveboxes e getTruck do recurso em Config.inventory_name. Encontrando item ilegal, late e faz a animação de alerta; senão, senta. A opção só aparece no menu se o jogador for police e o pet ativo for um dos modelos de Config.k9.models.

O modelo do K9 precisa ser streamado separadamente — ver Instalação.

Variações de cor

shared/shared.lua mapeia, por modelo, os nomes de variação e os componentId / drawableId / textureId correspondentes. Exemplos: A_C_Husky tem dark, brown e white; a_c_k9 tem GoldBlack, WhiteBrown, BlackBrown e Black; A_C_Poodle tem só white.

Uma variação é sorteada na inicialização do pet e gravada na metadata. Depois, o petgroomingkit permite trocá-la pela lista de variações do modelo.

Para adicionar uma variação nova, acrescente a entrada na tabela PetVariation do modelo. A função utilitária variationTester(ped, componentId) no mesmo arquivo imprime no console todas as combinações válidas de drawable/texture de um ped.

Integrações

ox_inventory

É a fonte da verdade do estado do pet. O recurso lê e escreve a metadata do slot (GetSlot, SetMetadata, GetInventoryItems) e remove itens consumíveis (RemoveItem). Os pets precisam ser cadastrados como itens não empilháveis.

ox_target

Registra as quatro opções no ped do pet (addEntity com o net ID) no momento em que ele é spawnado.

qb-inventory

Usado apenas pela busca em veículo do K9, via os exports getGloveboxes(plate) e getTruck(plate). O recurso é resolvido por Config.inventory_name, então qualquer inventário que exponha esses dois exports funciona.

qb-hud

Acariciar o pet dispara TriggerServerEvent('hud:server:RelieveStress', Config.Balance.petting_stress_relief). Sem um recurso que escute esse evento, o carinho apenas não alivia estresse — nada quebra.

Entrypoints para outros recursos

Evento keep-companion:client:callCompanion

Faz o client spawnar um pet. É o evento que o servidor dispara quando o jogador usa o item.

TriggerClientEvent('keep-companion:client:callCompanion', src, model, hostileTowardPlayer, item)

Evento keep-companion:client:despawn

Guarda o pet. Com revive = true, o pet é removido sem a barra de progresso (usado pelo revive, pela tosa e pela troca de dono).

TriggerClientEvent('keep-companion:client:despawn', src, item, revive)

Evento keep-companion:client:forceKill

Mata o pet imediatamente, com um motivo. O servidor usa com 'hunger' quando a fome zera a vida.

TriggerClientEvent('keep-companion:client:forceKill', src, hash, reason)

Callback keep-companion:server:search_inventory

Retorna true se o jogador com o ID informado carrega algum item de Config.k9.illegal_items.

QBCore.Functions.TriggerCallback('keep-companion:server:search_inventory', function(found) end, targetId)

Callback keep-companion:server:search_vehicle

Retorna true se o porta-luvas (key = 1) ou o porta-malas (key = 2) da placa informada tem item ilegal.

QBCore.Functions.TriggerCallback('keep-companion:server:search_vehicle', function(found) end, { key = 1, plate = plate })

Evento keep-companion:server:onPlayerUnload

Marca os pets de um jogador como despawnados. Deve ser disparado no logout.

Localização

As strings vêm do sistema de locale do qb-core (@qb-core/shared/locale.lua), com o objeto global Lang. Os arquivos ficam em locales/:

• pt-br.lua — português do Brasil (ativo)
• en.lua — inglês

O idioma não é escolhido por convar: o fxmanifest.lua carrega diretamente locales/pt-br.lua. Para usar inglês, troque essa linha no shared_scripts do manifest por locales/en.lua.

Parte das strings do menu e das notificações está fixa no código (em português), fora dos arquivos de locale.

O shared/badwords.lua traz a lista de palavras bloqueadas na hora de nomear um pet.

Estrutura de arquivos

mri_Qpets/
├── client/
│   ├── client.lua       — spawn/despawn, opções do ox_target, alimentar/beber/curar, thread AFK, dados do pet ativo
│   ├── functions.lua    — lógica de caça e perseguição, blips, spawn location, animações auxiliares
│   ├── menu.lua         — keybind, menus (ações, truques, troca de controle), busca do K9
│   ├── animator.lua     — dicionários e sequências de animação por espécie
│   └── c_util.lua       — utilitários de client
├── server/
│   ├── server.lua       — classe Pet, itens usáveis, spawn/despawn, revive, loop de save, comandos
│   └── functions.lua    — inicialização do item, gerador de nomes, XP/nível, fome/sede, troca de dono, cooldown
├── shared/
│   ├── shared.lua       — tabela PetVariation (variações de cor por modelo)
│   ├── util.lua         — helpers compartilhados
│   └── badwords.lua     — palavras bloqueadas em nomes de pet
├── locales/
│   ├── pt-br.lua        — carregado pelo fxmanifest
│   └── en.lua           — disponível, não carregado
├── config.lua           — pets, itens, balanceamento, settings, K9
├── inventory_images/    — 22 PNGs (um por pet e por item) para copiar no inventário
├── K9addon/             — ped addon a_c_k9 (data/peds.meta + stream/); precisa ir para um recurso de stream próprio
└── fxmanifest.lua