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) or QBCore (qb-core) or Qbox (qbx_core) | Auto-detected. Provides the UseItem hook for pet items. |
ox_inventory | Preferred inventory bridge. Falls back to the framework’s native inventory if missing. |
ox_lib | If started, the equip / unequip animation shows a progress bar. Otherwise the animation just plays for duration ms. |
Steps
-
Drop the
nex_shoulderpets folder into your resources/ tree, e.g.:
resources/[nex]/nex_shoulderpets
-
Drop the pet models stream resource into your resources too — see Pet models below.
-
Add both to your
server.cfg. Make sure nex_shoulderpets starts after your framework and (if used) ox_inventory:
-
Add the inventory items — see Inventory items below.
-
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:
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.
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.
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.
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:
Config.General.framework = 'standalone'
/spawnpet <petId> (the key in Config.Pets). The menu, shoulder switching, and particle effects all still work.
Checking it worked
From your server console:
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.
-
Replace the resource files with the new version (keep your edited
config.lua and client/editable.lua).
-
Restart the resource:
