Skip to main content
Everything lives in config.lua. Edit, then restart nex_shoulderpets. Custom pets are a topic of their own — see Adding pets.

​
General behaviour

Config.General = {
    framework = 'auto',   -- 'auto' | 'esx' | 'qbcore' | 'qbox' | 'standalone'
    inventory = 'auto',   -- 'auto' | 'ox_inventory' | 'native'

    resourceNames = {
        esx         = 'es_extended',
        qbcore      = 'qb-core',
        qbox        = 'qbx_core',
        oxInventory = 'ox_inventory',
    },

    menuCommand      = 'pet',         -- /pet
    keybind          = 'P',           -- default key
    standaloneSpawn  = 'spawnpet',    -- /spawnpet <id> (standalone mode)
    adminWipeCommand = 'removepet',   -- /removepet <id>
    adminAceCheck    = 'command.removepet',

    defaultShoulder = 'left',         -- 'left' | 'right'

    cooldowns = {
        effect  = 2500,   -- ms between particle triggers
        refresh = 4000,   -- ms between re-summons
    },

    debug = false,
}
auto picks whichever supported framework / inventory is running. Only set explicit values if your setup is unusual. The keybind registers via RegisterKeyMapping, so each player can rebind it under F1 → Settings → Key Bindings → FiveM. The slash command always works regardless of the keybind.

​
Animations

Equip and unequip animations play when a player uses a pet item or dismisses a pet from the menu. If ox_lib is started, an ox_lib progress bar is shown for the duration; otherwise the animation just plays for duration ms. 
equip = {
    duration = 2500,
    anim = {
        dict = 'mp_common',
        clip = 'givetake1_a',
        flag = 49,
    },
},

unequip = {
    duration = 2000,
    anim = {
        dict = 'mp_common',
        clip = 'givetake2_a',
        flag = 49,
    },
},
The default mp_common/givetake1_a is universally available in vanilla GTA V — plays on every ped, no DLC required. Flag 49 keeps the legs free so the player can still walk.
If the configured anim dict can’t be loaded, the client silently falls back to mp_common/givetake1_a so a typo can never block the pet from spawning.
Other vanilla anims confirmed safe on any ped:
Vibedictclip
Adjust tie at neckclothingtietry_tie_positive_a
Adjust shirtclothingshirttry_shirt_positive_d
Right hand up to headclothinghattry_hat_positive_a
Bend down + pickuprandom@domesticpickup_low
Forced removal (inventory drain to zero or admin /removepet) and the menu’s “Re-summon” skip the unequip animation — both are intentional quick respawns.

​
UI

ui = {
    locale       = 'en',        -- locales/<locale>.lua
    accent       = '#FFFFFF',   -- header / icon accent (any CSS color)
    side         = 'left',      -- 'left' | 'center' | 'right' menu anchor
    showCooldown = true,        -- show cooldown progress on the action buttons
}

​
Notifications

client/editable.lua exposes a single function: 
function NexShowNotification(message, kind)
    -- kind: 'success' | 'error' | 'inform'
    -- Default implementation uses the FiveM Thefeed ticker.
end
Replace the body to route through ESX.ShowNotification, QBCore.Functions.Notify, lib.notify, or whatever you use. The file is escrow_ignored so it survives updates.

​
Locales

locales/en.lua and locales/es.lua ship by default. To add another language:
  1. Copy locales/en.lua to locales/<your-lang>.lua (e.g. locales/fr.lua).
  2. Translate the strings.
  3. Set Config.General.ui.locale = 'fr'.
  4. Restart the resource.
The locales folder is loaded with locales/*.lua in the fxmanifest, so the new file is picked up automatically.