Skip to content

Configuration Guide

Everything lives in config.lua and stays editable in the encrypted version. Framework, inventory and notification settings are not part of this script; they are handled by vns-core.

Core options

Option Default What it does
Config.Progress bar / bottom ox_lib progress display: style = "bar" or "circle", position = "middle" or "bottom" (circle only)
Config.Lang - All player-facing strings
Config.DrawDistance 25 Distance at which the steal marker is drawn
Config.Cooldown 900 Per-player cooldown between missions, in seconds. Shared across all missions

Building a mission - Config.Reward

Each entry in Config.Reward is one mission. The key is the mission name and, for item-started missions, also the inventory item name. The default config ships blueusb, missionEasy, missionHard and redusb; copy one to add your own.

Config.Reward["myheist"] = {
    IsItem = false,     -- true: started by using the item "myheist"
                        -- false: started by an event (see below)
    PosCateg = 1,       -- which location pool from Config.MissionPosition
    NpcLevel = 2,       -- which weapon tier from Config.Weapons
    ...
}

Enemy settings

Option What it does
Bots Number of NPCs to spawn at random positions (within 45m) around the loot. Set to false to spawn them at the GoonSpawns coordinates of the chosen location instead, one NPC per coordinate
Peds List of ped models; each NPC picks a random one
NpcLevel Weapon tier index into Config.Weapons; each NPC gets a random weapon from that tier
Health NPC health (default missions use 200, the hard redusb mission 550)
Armor NPC armor, 0-100
Accuracy Shooting accuracy, 0-100
Vision How far the NPCs see and hear you before combat starts
Ability Combat ability: 1 = Poor, 2 = Average, 3 = Professional
Movement Combat movement: 0 = Stationary, 1 = Defensive, 2 = Offensive, 3 = Suicidal Offensive
Pattern Firing pattern name, e.g. "FIRING_PATTERN_BURST_FIRE_PISTOL" or "FIRING_PATTERN_FULL_AUTO"
HeadshotKill true: NPCs die to headshots. false: no critical hits, much harder

Reward settings

Option What it does
ItemAmount {min, max} - how many reward rolls the player gets at the end
ItemChance Percent chance (0-100) that each roll actually pays out
items Reward pool: {name = 'itemname', min = 1, max = 3} per entry. Each successful roll picks one random entry and gives a random amount between its min and max

So with ItemAmount = {min = 4, max = 6} and ItemChance = 50, the player gets 4-6 rolls and each roll has about a 50% chance to hand out one random item from the pool. Rewards are handed out one roll at a time, a fraction of a second apart.

Weapon tiers - Config.Weapons

Four numbered weapon pools, from basic pistols ([1]) up to shotguns and Mk2 rifles ([4]). A mission's NpcLevel selects the pool; every spawned NPC gets a random weapon from it. You can edit the pools or add your own tiers.

Locations - Config.MissionPosition

Location pools, keyed by the PosCateg a mission refers to. Each entry:

{
    Location = vector3(-520.12, -2877.79, 7.29),  -- the loot / steal marker
    InUse = false,                                -- DO NOT change - runtime flag
    GoonSpawns = {                                -- optional: fixed NPC positions
        vector3(-523.38, -2877.98, 7.29),
        ...
    }
},
  • When a mission starts, a random free location from the pool is picked and flagged InUse for everyone until the loot is stolen. If no free location is found, the player gets the noMissionAvailable message and an item mission's item is not removed.
  • GoonSpawns is only used when the mission has Bots = false; it spawns exactly one NPC per coordinate. With a numeric Bots, spawn positions are generated automatically around Location.
  • Pool [1] ships 35 city and countryside spots, pool [2] 8 harder spots, pool [3] one large compound with 20 spawn points.

Note

A pool used by a Bots = false mission must have GoonSpawns on all of its locations, otherwise no enemies spawn there.

Note

The server picks a free location first. The price is only charged, the item only used up and the cooldown only started once a location was found, so a player never pays for "no locations available".

Starting missions from other scripts

Missions with IsItem = false are started with an event. From the client:

-- TriggerServerEvent('vns_usbsystem:startmission', missionName, price)
TriggerServerEvent('vns_usbsystem:startmission', 'missionEasy', 300)

From the server (for example your own resource's shop or NPC logic), pass the player's server id as a third argument:

TriggerEvent('vns_usbsystem:startmission', 'missionEasy', 300, playerId)

Each mission's Price in config.lua is the minimum a client-side start costs:

Started from Charged
Server (TriggerEvent) The price you pass, or the mission's Price when you pass none.
Client (TriggerServerEvent) The price you pass, but never less than the mission's Price.
Client, mission has no Price Refused. Start it from an item or from the server instead.

This stops players from firing the event themselves with a price of 0. You can change the rule in ResolveMissionPrice in server/server_open.lua.

The default prices are 300 for missionEasy and 600 for missionHard. Change them in config.lua to fit your economy.

The server then:

  1. Checks the player is not on cooldown (Config.Cooldown) and has no mission running.
  2. Picks a free location from the mission's pool.
  3. Charges the price in cash and starts the cooldown.
  4. Starts the mission and sends the "follow your GPS" notification.

The reward is paid once, only for the mission the server started for that player, and only near its location.

This is how you hook the system into NPCs, laptops, target options, phone apps or shop items of your own; anything that can fire a server event.

Notifications

Other scripts can reuse the script's notification event:

TriggerClientEvent('vns-missionsystem:client:notification', src, message, type, duration, title)

type is inform (default), success or error; duration defaults to 5000 ms and title is optional. Notifications are shown through vns-core, so they follow Config.NotifySystem in vns-core/config.lua.

Advanced - NPC combat tuning

Config.CombatAttributes and Config.CombatFloats are applied to every spawned NPC once combat starts. They map directly to the SetPedCombatAttributes and SetCombatFloat natives (attribute/float ID -> value). Only change these if you know the natives involved.