> ## 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.

# Installation

> How to install NEX Shoulder Pets on your FiveM server.

## Requirements

None strictly required — the script runs **standalone**. If you do use a framework or inventory, it'll plug in automatically.

| Optional dependency                                                                                                                                                                                                | Notes                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **ESX** ([`es_extended`](https://github.com/esx-framework/esx_core)) **or QBCore** ([`qb-core`](https://github.com/qbcore-framework/qb-core)) **or Qbox** ([`qbx_core`](https://github.com/Qbox-project/qbx_core)) | Auto-detected. Provides the `UseItem` hook for pet items.                                                             |
| [`ox_inventory`](https://github.com/overextended/ox_inventory)                                                                                                                                                     | Preferred inventory bridge. Falls back to the framework's native inventory if missing.                                |
| [`ox_lib`](https://github.com/overextended/ox_lib)                                                                                                                                                                 | If started, the equip / unequip animation shows a progress bar. Otherwise the animation just plays for `duration` ms. |

## Steps

1. Drop the `nex_shoulderpets` folder into your `resources/` tree, e.g.:

   ```
   resources/[nex]/nex_shoulderpets
   ```

2. Drop the **pet models stream resource** into your resources too — see [Pet models](#pet-models) below.

3. Add both to your `server.cfg`. Make sure `nex_shoulderpets` starts **after** your framework and (if used) `ox_inventory`:

   ```
   ensure nex_shoulderpets
   ```

4. Add the inventory items — see [Inventory items](#inventory-items) below.

5. Restart your server. No SQL, no exports to wire up.

## Pet models

The bundled pets are distributed as a separate streaming bundle so you only ship the models you want:

* **Pet stream files (models):** [https://drive.google.com/file/d/1b6Qqxh1jNC0Tf3vTQQFbTY0m8ptvxXFb/view?usp=sharing](https://drive.google.com/file/d/1b6Qqxh1jNC0Tf3vTQQFbTY0m8ptvxXFb/view?usp=sharing)

Unzip into your `resources/` tree and add it to `server.cfg` like any other stream resource. The model name in each `Config.Pets[*].model` must match the `.ydr` filename (without the extension).

To add your own pets, see [Adding pets](/nex_shoulderpets/adding-pets).

## Inventory items

Pick the file that matches your inventory. Both ship inside the resource under `install/`.

### ox\_inventory

Append the entries from `install/items/ox_inventory.lua` into `ox_inventory/data/items.lua`. Drop a 100×100 PNG into `ox_inventory/web/images/` for each pet, named after the item key (e.g. `shark_boi.png`). Pet icons are bundled under `install/pets_images/` — just copy them across.

<Warning>
  **Do not set `consume = 0` on these items.** In Lua, `0` is truthy, so ox\_inventory takes its consume branch and never calls the framework's `UseItem` hook that nex\_shoulderpets listens on — the pet would never spawn. Leave `consume` unset to route through `server.UseItem` correctly. The script never removes the item, so the pet item stays in the player's inventory after use.
</Warning>

### Legacy ESX inventory

Run `install/items/esx.sql` against your database once. It adds one row per pet to the `items` table.

### QBCore / Qbox

Add each pet as a normal item in `qb-core/shared/items.lua`. Use the keys from `Config.Pets` as the item names (e.g. `shark_boi`, `monkey_punk`). The server bridge picks up `UseItem` automatically.

## Standalone mode

If you don't run any framework, set:

```lua theme={null}
Config.General.framework = 'standalone'
```

In standalone mode there's no inventory check — players summon pets directly with `/spawnpet <petId>` (the key in `Config.Pets`). The menu, shoulder switching, and particle effects all still work.

## Checking it worked

From your server console:

```
state nex_shoulderpets
```

Should print `started`. In-game, press **P** (or type `/pet`) — the menu should open. If `Config.General.debug = true` is set, F8 prints the resolved framework and inventory bridge on resource start.

## Updating

`config.lua`, `shared/bridge.lua`, the locales, and `client/editable.lua` are listed under `escrow_ignore`, so your custom pets, notification override, and translations survive updates.

1. Replace the resource files with the new version (keep your edited `config.lua` and `client/editable.lua`).
2. Restart the resource:

   ```
   restart nex_shoulderpets
   ```