QBCoreQBoxESXND_Coreox_core

Perks

XP-based perk system for FiveM. Players earn XP from activities (Fleeca heists, house robbery, fishing, mining, farming and more), level each category to 10, and spend perk points on bonuses in an item tablet. The framework is auto-detected, so there's no framework config to set.

💡

Other scripts read a player's level and perks through exports — that's how House Robbery wires its progression in. See Exports & Integration.

1. Dependencies

  • ox_lib (required)
  • oxmysql (required)
  • A framework, one of qb-core, qbx_core, es_extended, ND_Core, ox_core (auto-detected, no config needed)
  • An inventory to open the tablet from. ox_inventory, qb-inventory, ps-inventory, qs-inventory, lj-inventory, core_inventory and codem-inventory all work (auto-detected).

2. Drop in the resource

Place the jj-perks folder inside your resources directory. The folder must be named exactly jj-perks, since the inventory item export jj-perks.openTablet depends on it.

3. Database

Nothing to do. The three tables (jj_perks_players, jj_perks_unlocked, jj_perks_category_xp) create themselves the first time the server boots. If you'd rather create them ahead of time, import the included install.sql.

4. Add the perk tablet item

The tablet opens from an inventory item (perk_tablet by default; rename it in config.lua under Config.Item). The inventory is auto-detected, but how you register the item differs.

ox_inventory — add this to ox_inventory/data/items.lua inside the return { ... } table. The export line is what opens the UI; without it the item does nothing.

["perk_tablet"] = {
    label = "Perk Tablet",
    weight = 1000,
    stack = false,
    close = true,
    description = "A tablet that opens the perk progression system",
    client = {
        image = "perk_tablet.png",
        export = "jj-perks.openTablet"
    }
},

qb-inventory, ps-inventory, qs-inventory, lj-inventory, core_inventory, codem-inventory and ESX inventories — add perk_tablet to your framework's item list and mark it usable (useable = true on QBCore). jj-perks hooks the use itself, so you don't add an export.

ℹ️

Running something not listed? Copy modules/bridge/inventory/custom/server.lua, wire your inventory's usable-item export, and add it to inventoryResources in shared/main.lua. ND_Core and ox_core have no usable-item registry of their own, so on those frameworks use ox_inventory.

5. Add the item image

jj-perks/Images/perk_tablet.png   ->   ox_inventory/web/images/perk_tablet.png

Image standard: 100x100 PNG, content max 60x60, centered.

6. server.cfg load order

ensure ox_lib
ensure oxmysql
ensure qb-core          # or qbx_core / es_extended / ND_Core / ox_core
ensure ox_inventory
ensure jj-perks
⚠️

Order matters. jj-perks reads your framework on start. If it loads first you'll see "no supported framework detected". And if another resource (like jj-houserobbery) uses the jj-perks exports, jj-perks must start before it.

7. Start and verify

  1. Restart the server (or ensure jj-perks from the console).
  2. Give yourself the item: /giveitem <id> perk_tablet 1 (QBCore) or your inventory's give command.
  3. Use the item — the perk tablet should open.
  4. As an admin, confirm the Admin tab shows inside the tablet.
  5. Test progression: in the Admin tab, add some XP to a category for a player, then check it shows on their tablet.

Next: head to Configuration to add or edit categories.