Como adicionar itens no inventário FiveM: vRP, Creative, QBCore, Qbox e ESX

Hideki · 1 hora atrás

Adicionar um item não é apenas escrever um nome em um arquivo. O inventário precisa conhecer o identificador, nome exibido, peso, empilhamento, imagem, comportamento de uso e forma de persistência. Este guia mostra o fluxo completo e separa o que muda entre vRP, Creative, QBCore, Qbox e ESX.

Antes de começar

Backup do resource e do banco antes de alterar a produção.
Servidor de homologação ou uma janela de manutenção para testar restart, adicionar, remover e usar o item.
Identificação do inventário real em uso: vRP/Creative próprio, qb-inventory, ox_inventory, esx_inventory ou outro.
Imagem do item no formato e na pasta esperados pelo seu inventário; o nome do arquivo precisa coincidir com a configuração.

Passo a passo

Escolha um ID minúsculo, sem espaços e estável, por exemplo fdev_water. O ID é usado pelo código; o label pode conter acentos.
Defina o contrato do item: peso em gramas ou quilos, stack/unique, quantidade consumida, metadata, imagem e se ele será utilizável.
Abra a implementação da sua base e confirme o arquivo correto. Os locais mais comuns são qb-core/shared/items.lua, ox_inventory/data/items.lua, cfg/items.lua e a tabela SQL items.
Cadastre o item no formato do framework e crie o callback de uso no servidor. Dê o item somente depois de validar a origem, a quantidade e o limite de peso.
Teste o fluxo real: adicionar, abrir inventário, mover, usar, consumir, relogar e reiniciar o FXServer. Confira também o console e o log do banco.
Documente a alteração e mantenha uma migração reversível. Nunca sobrescreva arquivos do core durante uma atualização sem guardar o diff.

Erros comuns e cuidados

Não copie um cadastro QBCore para Qbox sem verificar se a cidade usa ox_inventory; Qbox frequentemente centraliza os itens no inventário, não no core.
Não confie em evento disparado pelo cliente para entregar item, dinheiro ou efeito. O servidor deve confirmar jogador, quantidade e permissão.
A tabela items do ESX muda entre versões e inventários customizados. Confira as colunas existentes antes de executar SQL.
vRP e Creative possuem forks com assinaturas diferentes. Trate os exemplos dessas bases como padrão de adaptação e confira a API já usada na sua cidade.
Após editar um arquivo Lua, reinicie o resource. Se o item continuar invisível, verifique nome da imagem, cache do inventário e erro de sintaxe antes de apagar cache indiscriminadamente.

Checklist final

ID único e documentado.
Peso, stack/unique e quantidade de consumo conferidos.
Cadastro feito no inventário correto.
Imagem aparece no slot.
Uso e remoção funcionam no servidor.
Item continua correto depois de relogar e reiniciar.
SQL ou configuração versionado e com backup.

Próximo passo: comece em um item de teste como fdev_water, valide em uma cidade de homologação e só então replique o padrão para comida, ferramentas, documentos e itens com metadata. Consulte também a documentação do QBCore Shared Items e do ox_inventory Creating Items.

Conteúdo revisado pela FiveMDEV. Faça backup antes de alterar uma cidade em produção.

Exemplos práticos

Use o mesmo contrato em qualquer base: um ID estável, um label amigável e uma regra de uso validada no servidor. O exemplo abaixo é a referência que será adaptada nos blocos seguintes.

Conteúdo oculto 🔒 Login necessário