Instalação

Dependências

O Five Pets possui apenas uma dependência obrigatória. A integração com o seu framework é feita através de um arquivo de adaptação separado — não existe acoplamento direto com nenhum framework específico.

oxmysql

Única dependência obrigatória. Responsável por toda a comunicação com o banco de dados MySQL/MariaDB.

Qualquer framework

ESX, QBCore, vRP, ox_core ou customizado. A integração é feita adaptando config/functions.lua.

O sistema de notificações detecta automaticamente o ox_lib e o utiliza se disponível. Caso contrário, usa o evento de notificação padrão do servidor.

Banco de Dados

As tabelas são criadas automaticamente na primeira inicialização do recurso. As estruturas abaixo servem apenas como referência.

Tabela de instâncias

Armazena cada pelúcia individualmente com seu nível, XP, benefícios e status de equip.

CREATE TABLE IF NOT EXISTS `core_pets_instances` (
  `id`            INT          NOT NULL AUTO_INCREMENT,
  `user_id`       INT          NOT NULL,
  `item_key`      VARCHAR(100) NOT NULL,
  `level`         INT          NOT NULL DEFAULT 1,
  `xp`            INT          NOT NULL DEFAULT 0,
  `benefits_json` TEXT,
  `equipped`      TINYINT      NOT NULL DEFAULT 0,
  `created_at`    TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  INDEX `idx_user_id`         (`user_id`),
  UNIQUE KEY `unique_user_item` (`user_id`, `item_key`),
  INDEX `idx_user_equipped`   (`user_id`, `equipped`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Tabela de pelúcia em destaque

Armazena a pelúcia marcada como destaque por cada jogador.

CREATE TABLE IF NOT EXISTS `core_pets_featured` (
  `user_id`  INT          NOT NULL,
  `item_key` VARCHAR(100) DEFAULT NULL,
  PRIMARY KEY (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Tabela de propostas de troca

Armazena propostas de troca de forma assíncrona — o destinatário não precisa estar online no momento da proposta. O campo status percorre os valores pending, accepted, declined, cancelled e failed.

CREATE TABLE IF NOT EXISTS `core_pets_trades` (
  `id`           INT          NOT NULL AUTO_INCREMENT,
  `from_user_id` INT          NOT NULL,
  `to_user_id`   INT          NOT NULL,
  `offer_json`   TEXT,
  `request_json` TEXT,
  `status`       VARCHAR(20)  NOT NULL DEFAULT 'pending',
  `message`      VARCHAR(200),
  `created_at`   TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `resolved_at`  TIMESTAMP    NULL,
  PRIMARY KEY (`id`),
  INDEX `idx_to_user_status`   (`to_user_id`, `status`),
  INDEX `idx_from_user_status` (`from_user_id`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Tabela legada (compatibilidade)

Mantida apenas para que a migração das coleções antigas para o novo formato de instâncias funcione. Não é mais escrita pelo recurso.

CREATE TABLE IF NOT EXISTS `core_pets_collections` (
  `id`       INT          NOT NULL AUTO_INCREMENT,
  `user_id`  INT          NOT NULL,
  `item_key` VARCHAR(100) NOT NULL,
  `qty`      INT          NOT NULL DEFAULT 0,
  PRIMARY KEY (`id`),
  UNIQUE KEY `unique_user_item` (`user_id`, `item_key`),
  INDEX `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Instalação do Recurso

Copie a pasta do recurso

Coloque a pasta core-pets dentro do diretório de recursos do seu servidor (ex: resources/[core]/).

Informe o token de licença

Abra o arquivo token.lua na raiz do recurso e substitua SEU-TOKEN-AQUI pelo token recebido.

token.lua

exports('license', function ()
    return 'SEU-TOKEN-AQUI'
end)

Adapte o config/functions.lua

Arquivo único de integração com o seu framework. Veja a seção Adaptação de Framework abaixo.

Configure o recurso

Edite os arquivos em config/ conforme descrito na seção Configuração.

Adicione à server.cfg

Certifique-se de iniciar o recurso após o oxmysql e o seu framework.

ensure oxmysql
ensure seu-framework
ensure core-pets

Adaptação de Framework

Toda a comunicação com o framework está isolada em config/functions.lua. Para integrar com o framework do seu servidor, implemente as seguintes funções nesse arquivo:

Identificação do jogador

O script precisa de um identificador numérico único por jogador para associar dados no banco.

-- Retorna o ID único do jogador a partir do source (server ID)
function Functions.getUserId(source)
    -- Exemplo vRP (Creative Enchanted):
    return vRP.Passport(source)

    -- Exemplo vRPex / vRP padrão:
    -- return vRP.getUserId(source)

    -- Exemplo ESX:
    -- local xPlayer = ESX.GetPlayerFromId(source)
    -- return xPlayer and xPlayer.getIdentifier() or nil

    -- Exemplo QBCore:
    -- local Player = QBCore.Functions.GetPlayer(source)
    -- return Player and Player.PlayerData.citizenid or nil

    -- Exemplo standalone (usa o próprio source):
    -- return source
end

-- Retorna o source do jogador a partir do ID único
function Functions.getUserSource(userId)
    -- Exemplo vRP (Creative Enchanted):
    return vRP.Source(userId)

    -- Exemplo vRPex / vRP padrão:
    -- return vRP.getUserSource(userId)

    -- Exemplo ESX:
    -- for _, xPlayer in pairs(ESX.GetExtendedPlayers()) do
    --     if xPlayer.getIdentifier() == userId then return xPlayer.source end
    -- end

    -- Exemplo QBCore:
    -- for _, src in ipairs(QBCore.Functions.GetPlayers()) do
    --     local Player = QBCore.Functions.GetPlayer(src)
    --     if Player and Player.PlayerData.citizenid == userId then return src end
    -- end
end

-- Retorna o nome completo do jogador
function Functions.getUserName(userId)
    -- Exemplo vRP (Creative Enchanted):
    return vRP.FullName(userId)

    -- Exemplo vRPex / vRP padrão:
    -- local identity = vRP.getUserIdentity(userId)
    -- return identity and (identity.firstname .. " " .. identity.name) or "Desconhecido"

    -- Exemplo ESX:
    -- local xPlayer = ESX.GetPlayerFromIdentifier(userId)
    -- return xPlayer and xPlayer.getName() or "Desconhecido"

    -- Exemplo QBCore:
    -- local Player = QBCore.Functions.GetPlayerByCitizenId(userId)
    -- if Player then
    --     local ci = Player.PlayerData.charinfo
    --     return ci.firstname .. " " .. ci.lastname
    -- end
    -- return "Desconhecido"
end

Permissões de admin

Controla quem pode acessar o painel administrativo (/petsadm). Suporta permissão única (string) ou conjunto de permissões (table).

-- Retorna true se o jogador tiver a permissão informada
function Functions.hasPermission(userId, permission)
    if not permission then return true end

    -- Exemplo vRP (Creative Enchanted) — suporta string ou table:
    if type(permission) == "table" then
        local result = vRP.HasTable(userId, permission)
        if type(result) == "number" then return result >= 1 end
        return result == true
    end
    local result = vRP.HasPermission(userId, permission)
    if type(result) == "number" then return result >= 1 end
    return result == true

    -- Exemplo vRPex / vRP padrão:
    -- return vRP.hasPermission(userId, permission)

    -- Exemplo ESX (por grupo):
    -- local xPlayer = ESX.GetPlayerFromIdentifier(userId)
    -- return xPlayer and xPlayer.getGroup() == permission or false

    -- Exemplo QBCore:
    -- local Player = QBCore.Functions.GetPlayerByCitizenId(userId)
    -- return Player and Player.PlayerData.permission == permission or false

    -- Exemplo standalone (ace permissions):
    -- return IsPlayerAceAllowed(tostring(Functions.getUserSource(userId)), permission)
end

O valor de permission verificado é o definido em Pets.AdminPermission no config/config.lua. Ajuste-o para corresponder ao sistema de permissões do seu framework (ex: "admin", "superadmin", "god").

Inventário

Funções de leitura e escrita no inventário do jogador. São usadas pela aba de Depósito/Saque do painel e pelo handler de “usar item” para dar a pelúcia diretamente do inventário.

-- Retorna a tabela de inventário do jogador
function Functions.getInventory(userId)
    -- Exemplo vRP (Creative Enchanted):
    return vRP.Inventory(userId)
end

-- Retorna (amount, name, slot) de um item específico no inventário
function Functions.getInventoryItemAmount(userId, item)
    -- Exemplo vRP (Creative Enchanted):
    local data = vRP.InventoryItemAmount(userId, item) or {}
    return tonumber(data[1]) or 0, data[2] or item, data[3]
end

-- Remove um item do inventário do jogador. Retorna true em sucesso.
function Functions.tryGetInventoryItem(userId, item, amount)
    -- Exemplo vRP (Creative Enchanted) com fallback por slot:
    if vRP.TakeItem(userId, item, amount, true) then
        return true
    end
    for _ = 1, amount do
        local itemAmount, itemName = Functions.getInventoryItemAmount(userId, item)
        if itemAmount <= 0 or itemName == "" then return false end
        if not vRP.TakeItem(userId, itemName, 1, false) then return false end
    end
    return true

    -- Exemplo vRPex / vRP padrão:
    -- return vRP.tryGetInventoryItem(userId, item, amount, true)

    -- Exemplo ESX:
    -- local xPlayer = ESX.GetPlayerFromIdentifier(userId)
    -- if xPlayer and xPlayer.getInventoryItem(item).count >= amount then
    --     xPlayer.removeInventoryItem(item, amount); return true
    -- end
    -- return false

    -- Exemplo QBCore:
    -- local Player = QBCore.Functions.GetPlayerByCitizenId(userId)
    -- return Player and Player.Functions.RemoveItem(item, amount) or false
end

-- Adiciona um item ao inventário do jogador
function Functions.giveInventoryItem(userId, item, amount)
    -- Exemplo vRP (Creative Enchanted):
    return vRP.GenerateItem(userId, item, amount, true)

    -- Exemplo vRPex / vRP padrão:
    -- return vRP.giveInventoryItem(userId, item, amount, true)

    -- Exemplo ESX:
    -- local xPlayer = ESX.GetPlayerFromIdentifier(userId)
    -- if xPlayer then xPlayer.addInventoryItem(item, amount) end

    -- Exemplo QBCore:
    -- local Player = QBCore.Functions.GetPlayerByCitizenId(userId)
    -- if Player then Player.Functions.AddItem(item, amount) end
end

Anticheat (spawn de prop)

Chamada server-side antes de qualquer prop ser criado no client. Use para whitelistar o modelo no seu anticheat. Retornar false aborta o spawn para aquele jogador.

function Functions.OnPropSpawn(source, data)
    -- Exemplo com PL_PROTECT:
    -- exports["PL_PROTECT"]:setSpawnClient(source, data.prop)
    return true
end

Campos disponíveis em data

Campo	Tipo	Descrição
`prop`	`string`	Nome do modelo do prop
`bone`	`number`	Bone de attach no ped
`posX/Y/Z`	`number`	Posição de offset
`rotX/Y/Z`	`number`	Rotação de offset
`dict`	`string`	Dicionário de animação
`anim`	`string`	Nome da animação
`flag`	`number`	Flag da animação
`itemKey`	`string`	Chave da pelúcia no catálogo
`requestId`	`string`	ID único da requisição

Se o seu anticheat não precisa de integração explícita para props, basta manter return true sem alterações.

Notificações

Disparada server-side via Functions.notify(source, type, message, duration). O tipo informado (success, denied, warning, info, error) é traduzido para a cor esperada pelo seu sistema antes de chamar o evento de notificação.

-- Mapeia o tipo lógico para a cor esperada pelo seu evento de notificação
local NOTIFY_BASE_TYPES = {
    success = "verde",
    denied  = "vermelho",
    warning = "amarelo",
    info    = "azul",
    error   = "vermelho",
}

function Functions.notify(source, notifyType, message, duration)
    if not source then return false end
    local normalizedType = string.lower(tostring(notifyType or "info"))
    local text  = tostring(message or "")
    local timer = duration or 5000

    -- Adapte o nome do evento para o seu framework:
    --   ex: "Notify", "esx:showNotification", "QBCore:Notify"
    TriggerClientEvent("Notify", source, "Pets", text,
        NOTIFY_BASE_TYPES[normalizedType] or normalizedType, timer)
    return true
end

No client-side, se o ox_lib estiver carregado, o Five Pets utiliza lib.notify automaticamente para suas notificações internas — sem necessidade de alteração.

Banco de dados

Wrappers que isolam o acesso ao MySQL. A implementação padrão usa o oxmysql, mas você pode trocar por outro driver mantendo a assinatura.

function Functions.query(command, params)
    return MySQL.query.await(command, params or {})
end

function Functions.update(command, params)
    return MySQL.update.await(command, params or {})
end

function Functions.single(command, params)
    if MySQL.single and MySQL.single.await then
        return MySQL.single.await(command, params or {})
    end
    local rows = Functions.query(command, params)
    return rows and rows[1] or nil
end

As tabelas do recurso são criadas automaticamente na primeira inicialização, então essas funções precisam estar funcionando antes da primeira chamada de ensure core-pets.

Configuração

config/config.lua — Configurações principais

Comandos e permissões

Pets.Command         = "pets"     -- Abre o painel do jogador
Pets.AdminCommand    = "petsadm"  -- Abre o painel de admin
Pets.AdminPermission = "Admin"    -- Permissão necessária para admin
Pets.ThemeColor      = "#0143bb"  -- Cor principal da interface (hex)

Funcionalidades (liga/desliga subsistemas)

Pets.Features = {
    Benefits = true,  -- false: exports neutros (0/1.0), GrantXP no-op, UI sem benefícios
    Fusion   = true,  -- false: aba "Aprimoramento" some e os handlers rejeitam
    Trade    = true,  -- false: aba "Trocas" some e os handlers rejeitam
}

Cada flag em false transforma o subsistema em no-op, sem mexer na coleção do jogador. Os pets continuam podendo ser equipados normalmente.Objetos 3D (defaults usados quando o catálogo não especifica)

Pets.Objects = {
    DefaultBone = 28422,
    DefaultFlag = 49,
}

Fusão

Pets.Fusion = {
    BaseChance        = 60,  -- Chance base quando target = maior raridade dos inputs (%)
    RarityJumpPenalty = 25,  -- Penalidade por tier acima do natural (%)
    SameRarityBonus   = 10,  -- Bônus se ambas têm a mesma raridade (%)
    MaxChance         = 90,
    MinChance         = 1,
}

Raridades, benefícios e XP por nívelDefinidos em Pets.Rarities, Pets.Benefits e Pets.XpPerLevel. Para cada raridade você ajusta multiplier, dropWeight, maxLevel e benefitCount. Para cada benefício, define type (flat ou percent), os 10 valores de levels, o label exibido na UI, o poolWeight no sorteio e o xpPerAction concedido por chamada do export GrantXP.

config/catalog.lua — Catálogo de pelúcias

Define todas as pelúcias disponíveis. As chaves de raridade aceitas são commom, uncommom, rare, epic e legendary — exatamente como em Pets.Rarities.Variante single-position — uma única posição de equip:

["chave_unica"] = {
    type     = "collection",
    name     = "Nome Exibido",
    category = "Categoria",
    rarity   = "rare",
    icon     = "https://cdn.fivenetwork.dev/...",
    prop = {
        model  = "nome_do_modelo",
        loop   = true,
        moving = true,
        bone   = 24818,
        pos    = { x = 0.30, y = 0.04, z = -0.30 },
        rot    = { x = -90.0, y = -90.0, z = 0.0 },
        anim   = { dict = "petcarinhoanimation@joao", name = "carinho_clip", flag = 49 }
    }
}

Variante multi-position — várias posições selecionáveis pelo jogador:

["chave_unica"] = {
    type     = "collection",
    name     = "Nome Exibido",
    category = "Categoria",
    rarity   = "legendary",
    icon     = "https://cdn.fivenetwork.dev/...",
    prop = {
        model  = "modelo_padrao",
        loop   = true,
        moving = true,
        positions = {
            {
                id    = "na_mao",
                label = "Na Mão",
                bone  = 12844,
                pos   = { x = 0.29, y = 0.08, z = 0.0 },
                rot   = { x = 0.0,  y = -270.0, z = 180.0 },
                model = "modelo_da_posicao"   -- opcional, sobrescreve o model raiz
            },
            -- outras posições…
        }
    }
}

Em ambas as variantes os campos bone/flag caem para os defaults de Pets.Objects quando não preenchidos.

config/webhooks.lua — Webhooks do Discord

webhookURLs = {
    give     = "",  -- Item adicionado via admin
    remove   = "",  -- Item removido via admin
    trade    = "",  -- Proposta enviada, aceita ou recusada
    featured = "",  -- Destaque alterado
    deposit  = "",  -- Depósito no painel
    withdraw = "",  -- Saque do painel
    fusion   = "",  -- Resultado de fusão (sucesso ou falha)
}

Deixe qualquer URL como "" para desativar aquele webhook.

Comece por aqui!

Nossos produtos

Dependências

oxmysql

Qualquer framework

Banco de Dados

Instalação do Recurso

Adaptação de Framework

Configuração

​Dependências

oxmysql

Qualquer framework

​Banco de Dados

​Instalação do Recurso

​Adaptação de Framework

​Configuração

Dependências

Banco de Dados

Instalação do Recurso

Adaptação de Framework

Configuração