> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexdev.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Everything lives in config.lua. Edit, then restart nex_shoulderpets.

Everything lives in `config.lua`. Edit, then `restart nex_shoulderpets`.

Custom pets are a topic of their own — see [Adding pets](/nex_shoulderpets/adding-pets).

## General behaviour

```lua theme={null}
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.

```lua theme={null}
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.

<Info>
  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.
</Info>

Other vanilla anims confirmed safe on any ped:

| Vibe                  | dict              | clip                   |
| --------------------- | ----------------- | ---------------------- |
| Adjust tie at neck    | `clothingtie`     | `try_tie_positive_a`   |
| Adjust shirt          | `clothingshirt`   | `try_shirt_positive_d` |
| Right hand up to head | `clothinghat`     | `try_hat_positive_a`   |
| Bend down + pickup    | `random@domestic` | `pickup_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

```lua theme={null}
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:

```lua theme={null}
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_ignore`d 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.