Exports

🔌 Exports API

FS-Pets exposes a set of read-only exports for server owners and developers who need to integrate the pet system with other resources — minigames, jobs, HUDs, or custom scripts.

note

All exports are informational. They read the current state of the pet system and do not modify it.

---

Server-Side Exports

HasActivePet

Returns whether a player currently has an active (spawned) pet.

---@param src number  Player server ID
---@return boolean
local hasPet = exports['fs-pets']:HasActivePet(src)

---

GetActivePet

Returns the full active pet data for a player, or nil if none.

---@param src number  Player server ID
---@return table|nil  { id, hunger, thirst, energy }
local pet = exports['fs-pets']:GetActivePet(src)

if pet then
    print(pet.id, pet.hunger, pet.thirst, pet.energy)
end

Field	Type	Description
id	number	Database row ID of the active pet
hunger	number	Current hunger value (0–100)
thirst	number	Current thirst value (0–100)
energy	number	Current energy value (0–100)

---

GetPetStats

Returns only the stats of the active pet, or nil if none.

---@param src number  Player server ID
---@return table|nil  { hunger, thirst, energy }
local stats = exports['fs-pets']:GetPetStats(src)

if stats and stats.hunger < 20 then
    -- Trigger a low hunger warning, reward the player for feeding, etc.
end

tip

Use GetPetStats when you only need the numeric values and don't need the database ID.

---

Client-Side Exports

HasActivePet

Returns whether the local player currently has an active (spawned) pet.

---@return boolean
local hasPet = exports['fs-pets']:HasActivePet()

---

GetActivePetEntity

Returns the entity handle of the active pet ped, or nil if none.

---@return number|nil
local petEntity = exports['fs-pets']:GetActivePetEntity()

if petEntity then
    local coords = GetEntityCoords(petEntity)
end

tip

This is the most useful export for scripts that need to work with the pet's position, attach props, or check proximity.

---

GetActivePetData

Returns metadata about the active pet, or nil if none.

---@return table|nil  { id, name, model, texture, animType }
local data = exports['fs-pets']:GetActivePetData()

if data then
    print(data.name, data.model, data.animType)
end

Field	Type	Description
id	number	Database row ID
name	string	Pet's display name
model	string	GTA V model name
texture	number	Texture variation index
animType	string	Animation set key ("dog", "cat", "pug", etc.)

---

GetActivePetStats

Returns the active pet's current stat values, or nil if none.

---@return table|nil  { hunger, thirst, energy }
local stats = exports['fs-pets']:GetActivePetStats()

if stats then
    -- Use stats.hunger, stats.thirst, stats.energy
end

note

Client-side stats are updated in real time by the server via net events. They are always current.

---

IsPetSleeping

Returns whether the active pet is currently in a sleeping state.

---@return boolean
local sleeping = exports['fs-pets']:IsPetSleeping()

Useful for disabling interactions or commands that shouldn't be available while the pet is resting.

---

Usage Examples

Deny an action if the player has no pet:

-- Server-side
RegisterNetEvent('myscript:doSomething', function()
    local src = source
    if not exports['fs-pets']:HasActivePet(src) then
        return TriggerClientEvent('myscript:notify', src, "You need an active pet.")
    end
    -- Continue logic...
end)

Read pet position from client:

-- Client-side
local entity = exports['fs-pets']:GetActivePetEntity()
if entity then
    local petCoords = GetEntityCoords(entity)
    local playerCoords = GetEntityCoords(PlayerPedId())
    local distance = #(petCoords - playerCoords)
    print("Pet is " .. distance .. " meters away.")
end

Gate a zone interaction behind pet ownership:

-- Client-side
exports.ox_target:addBoxZone({
    coords  = vector3(100.0, 200.0, 30.0),
    size    = vector3(2, 2, 2),
    options = {
        {
            label  = "Dog Park Entry",
            icon   = "fa-solid fa-paw",
            onSelect = function()
                if not exports['fs-pets']:HasActivePet() then
                    lib.notify({ title = "You need a pet to enter.", type = "error" })
                    return
                end
                -- Open zone or trigger event...
            end
        }
    }
})