Skip to content

Installation

1. Dependencies

Make sure these are installed and started before vns-usbsystem:

  • 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)
  • mhacking - the hacking minigame. It is listed as a dependency in fxmanifest.lua, so the script won't start without it. To use a different minigame, see Using another hacking minigame.

vns-core detects your framework and inventory automatically and registers the USBs as usable items. The script has no framework settings of its own and doesn't use the database.

2. Resource

Copy the vns-usbsystem folder into your resources and start it after its dependencies:

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

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-usbsystem 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-usbsystem. The server script refuses to run under any other name and prints a warning in the console.

3. Items

Every key in Config.Reward becomes a usable item, and every reward item must exist in your inventory. With the default config:

Item name Used for
greenusb Tier 1 mission, rewards weed500g
whiteusb Tier 1 mission, rewards coke500g
blueusb Tier 1 mission, rewards meth500g
blackusb Hard mission, rewards one of reddiamond / yellowdiamond / bluediamond
purpleusb Military mission, rewards documents

The reward items are examples - replace them in config.lua with items your server actually has.

4. Using another hacking minigame

The hack goes through StartHackMinigame(level, duration, onFinish) in client/client_open.lua. Replace its body with your own minigame and call onFinish(true) on success or onFinish(false) on failure. level and duration come from Config.HackLevel and Config.HackTime. If you remove mhacking completely, also remove 'mhacking' from the dependencies block in fxmanifest.lua.

5. First start

  1. Start the server and give yourself a greenusb.
  2. Use it - after the 8-second connecting phase the hacking minigame opens.
  3. Pass the hack, follow the GPS route, fight the guards and press E at the marker. The reward lands in your inventory.

Encrypted variant

config.lua, locales/*.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, and the script now runs on QBCore and QBox as well as ESX.
  • mysql-async is no longer needed - the script doesn't use the database at all.
  • progressBars is no longer needed. Config.ProgressBars still exists, but the bars are now shown through vns-core.
  • mhacking is still required, but can now be swapped through the StartHackMinigame hook.
  • Removed options: Config.ESX, Config.OLDESX, and the unused Config.ZoneSize, Config.Hair, Config.Torso, Config.Pants, Config.Shoes and Config.Helmet.
  • Cooldown only starts once a mission really begins (after a successful hack and an assigned location). A failed hack or no free location no longer puts the player on cooldown. A player also can't start a second USB while a mission is active.
  • Rewards are validated server-side - paid once, from the server's own record of the mission, and only near the mission location. Items that don't fit in the inventory show the new inventory_full text.
  • Locales no longer use the ESX locale system - the script ships its own loader in locales/locale.lua. New language files in locales/ are picked up automatically.