#Installation

#Drop the files in your server

Start by dropping the files included in the resource from keymaster into your resources folder, then ensure the resource in your server.cfg:

ensure upgrade-rewards

The resource must start after your framework. If you start resources in a specific order, put upgrade-rewards below qb-core / qbx_core / es_extended.

#Dependencies

The only requirement is a framework - QBCore, QBox or ESX - and oxmysql. The framework is auto-detected, so there is nothing to set.

Your inventory is also auto-detected (ox_inventory, qb-inventory, ps-inventory, qs-inventory, lj-inventory, and the ESX default). If detection ever picks the wrong one, set Config.Inventory yourself.

Your garage script is detected the same way, so vehicle rewards land in a garage the player can actually pull from. See Configuration if a rewarded vehicle does not appear.

#Database

The resource creates and migrates its own tables on start, so there is no SQL to import. Four tables are created:

upgrade_rewards - one row per player: points, level, XP, playtime, referral code and history
upgrade_referrals - one row per successful referral
upgrade_purchases - purchase records, used by the per-item daily limits and cooldowns
upgrade_admin_log - the admin audit log

A rewards.sql file is included for reference only, for anyone who wants to provision the tables ahead of time or hand them to a DBA.

#Check the console on first start

The resource prints what it detected and what your config resolved to. A healthy start looks like this:

[Upgrade-Rewards] Version 1.5.4 loaded
[Upgrade-Rewards] Server bridge ready (QBCore / ox_inventory)
[Upgrade-Rewards] Vehicle rewards -> player_vehicles (garage column: garage, stored column: state, garage script: qb-garages)
[Upgrade-Rewards] Database setup complete!
[Upgrade-Rewards] Config check passed
[Upgrade-Rewards] Level system: mode scaling | XP needed 1->2: 100, 2->3: 150, 5->6: 506, 10->11: 3844 | XP per playtime reward: 10 (every 60 min), referral: 50 / 100

Those last two lines are worth reading before you open the game. The config check lists anything it believes is wrong - an unknown item type, a shop selling a loot case that does not exist, a cash reward set up as an item - and the level line tells you exactly how much XP each level actually needs with your current config.

#Configure it

Everything is in config.lua, which is not escrowed, and neither is the locales/ folder if you want to change any wording. Start with Configuration.

Players open the rewards menu with F11 by default (Config.UI.OpenKey, rebindable by each player through the FiveM keybind settings) or the /rewards command. Admins open the management panel with /rewards-admin.

#Updating from an older version

Replace the resource folder and restart. Keep your own config.lua - every option added since 1.0.5 has a safe default, so an older config still starts and behaves the way it did before. Database migrations run automatically, including the columns and tables added in later versions.

Two things to review after updating from 1.5.1 or earlier:

Config.LevelSystem gained a Mode and its own XP block. Until you set them, leveling behaves as it did before. See Leveling & XP.
The admin panel's "Add Points" button no longer grants XP on the side. Use "Grant XP", or set Config.LevelSystem.XP.AdminPointsRatio = 0.1 to restore the old behaviour.

If you are updating from 1.5.2 or earlier, Config.GetOutOfJailCost and Config.UnjailClientEvent have been replaced by a shop item and the Config.Jail block - see Shops & Loot.