Skip to content

Installation

1. Dependencies

Make sure these are installed and started before the Lucky Wheel:

  • Your framework: qb-core, qbx_core or es_extended
  • ox_lib
  • oxmysql
  • vns-core - free and open source, downloaded separately from your Keymaster/cfx Portal (it is not inside the script zip and updates on its own)

vns-core detects your framework, inventory and notification system automatically. The Lucky Wheel has no framework or inventory settings of its own.

2. Resource

Copy the vns-wheel folder into your resources and start it after vns-core:

ensure qb-core        # or qbx_core / es_extended
ensure ox_lib
ensure oxmysql
ensure vns-core
ensure vns-wheel

Ensure order

  • vns-core must be ensured after ox_lib, oxmysql (database), your framework, inventory, target system and your other server scripts such as housing, garages and phone.
  • vns-wheel must be ensured after vns-core.

If vns-core starts too early, VNS scripts can't use your database, items, money or other systems. See Installing vns-core.

Folder name

The folder must be named vns-wheel. The server script refuses to run under any other name and prints a warning in the console.

3. Database

Nothing to import. On first start the script creates its own table, vns_wheel_spins, which stores the time of each player's last daily spin.

4. Wheel placement

The script builds the wheel from the game's own props so it can animate the spin. Three setups are supported:

  • K4MB1 casino map: set Config.K4MB1_Casino_Map = true. The script finds the map's wheel prop automatically and places its animated wheel there; the podium car uses the map's podium. No coordinates needed.
  • Your map already has a Lucky Wheel prop: set Config.K4MB1_Casino_Map = false and Config.SpawnWheel = false, and point Config.WheelPos at the existing wheel.
  • Your map has no wheel: set Config.K4MB1_Casino_Map = false and Config.SpawnWheel = true, and set Config.WheelPos to where the wheel should stand.

For non-K4MB1 maps also set Config.VehiclePos (podium display car). Config.VehicleWinPos (where a won car spawns, with the winner seated inside) is used on every map.

5. Prize items

Every prize with type = 'item' must exist in your inventory under exactly the name used in Config.Prices. The default prize table uses:

Item Used for
casinochips The chip prizes (1,000 - 50,000), the same chips the other VNS casino scripts use
diamond The rare item prizes
weapon_pistol The mystery prize
scratchcard The small item prizes

Replace these with items your server actually has. If an item can't be given, the player gets the item_missing notification instead.

6. Vehicle prize: fuel and keys

A won car is registered as owned through vns-core on every framework, then spawned at Config.VehicleWinPos. Three hooks in client/client_open.lua let you adapt the spawn to your other resources:

Hook Default Change it when
SpawnPrizeVehicle(model, coords, heading, cb) Spawns the car through vns-core You want to spawn it differently.
SetVehicleFuel(vehicle, level) Native SetVehicleFuelLevel Your fuel resource tracks fuel itself - e.g. exports['LegacyFuel']:SetFuel(vehicle, level) or exports['ox_fuel']:setFuel(vehicle, level).
GiveVehicleKeys(vehicle, plate) Triggers vehiclekeys:client:SetOwner (qb-vehiclekeys and compatible) You use a different key system.

7. First start

  1. Start the server and check the console for errors.
  2. Walk to the wheel - you should see the podium car rotating and get the "Press E to spin the Lucky Wheel" help text at the wheel.
  3. Spin it. The wheel animates for everyone nearby and the prize lands in your inventory or bank.
  4. With Config.DailySpin on, a second spin before the next reset tells you that you have already spun.

Encrypted variant

config.lua, client/client_open.lua and server/server_open.lua stay editable in the Encrypted variant - everything on this page and the Configuration page can be changed in both variants.

Updating from the previous version

  • vns-core is now required. Install it and start it before vns-wheel.

  • No SQL import. Daily spins are stored in the new vns_wheel_spins table, created automatically. The old wheel column on your players table is no longer used and can be dropped:

    ALTER TABLE players DROP COLUMN wheel;   -- QBCore / QBox
ALTER TABLE users DROP COLUMN wheel;     -- ESX

    Existing daily-spin flags are not carried over, so every player gets one spin after updating.

  • Removed options: Config.Framework, Config.FrameworkFolder and Config.Inventory. The QBox manifest lines are gone too.

  • Texts moved to Config.Lang in config.lua.
  • Vehicle prizes work on every framework. The car is registered through vns-core instead of a QBCore-only player_vehicles insert.
  • LegacyFuel is no longer required. Fuel and keys go through the SetVehicleFuel and GiveVehicleKeys hooks in client/client_open.lua - put your fuel export there if you used LegacyFuel.
  • Prizes are decided and paid server-side. The server rolls the prize and only pays out its own pending record for that player.
  • Daily reset changed. Instead of clearing a flag at Config.ResetSpin, a player can spin again once their last spin is older than the most recent reset time - so a reset missed during a restart still counts.
  • Editable files renamed. server/open_server.lua is now server/server_open.lua, plus the new client/client_open.lua.