Installation

1. Download Resource

Download the purchased resource from CFX Portal - the official site of FiveM with purchased resources.

---

2. Import Database Tables

This is a very important step - without it, the script will not work properly. Depending on the framework you are using (ESX or QB-Core), select the appropriate section below and paste the SQL code into your database.

Not sure how to do it?

No worries - we've prepared a short guide that shows you step by step how to import an SQL file into your database: 👉 Click here to view the tutorial.

Database for ESX

ALTER TABLE `users` ADD COLUMN IF NOT EXISTS `status` longtext DEFAULT NULL;

CREATE TABLE IF NOT EXISTS `needs` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `item` varchar(50) NOT NULL,
    `model` varchar(50) NOT NULL,
    `position` longtext NOT NULL,
    `bucket` int(11) DEFAULT 0,
    `metadata` longtext DEFAULT NULL,
    `createdAt` bigint(20) DEFAULT NULL,
    `createdBy` varchar(100) DEFAULT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

Database for QB-Core

ALTER TABLE `players` ADD COLUMN IF NOT EXISTS `status` longtext DEFAULT NULL;

CREATE TABLE IF NOT EXISTS `needs` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `item` varchar(50) NOT NULL,
    `model` varchar(50) NOT NULL,
    `position` longtext NOT NULL,
    `bucket` int(11) DEFAULT 0,
    `metadata` longtext DEFAULT NULL,
    `createdAt` bigint(20) DEFAULT NULL,
    `createdBy` varchar(100) DEFAULT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

---

3. Add Items

The script uses its own items. Depending on what inventory you are using, select the appropriate section and add these items to either your item file or database.

Items for ox_inventory

['sandwich'] = {
    label = "Sandwich",
    weight = 80,
    stack = false,
    allowArmed = false,
    degrade = 720,
},
['burger'] = {
    label = 'Burger',
    weight = 120,
    stack = false,
    allowArmed = false,
    degrade = 360,
},
['hotdog'] = {
    label = "Hot-Dog",
    weight = 100,
    stack = false,
    allowArmed = false,
    degrade = 360,
},
['apple'] = {
    label = "Apple",
    weight = 60,
    stack = false,
    allowArmed = false,
    degrade = 720,
},
['water'] = {
    label = 'Water',
    weight = 500,
    stack = false,
    allowArmed = false,
    degrade = 4320,
},
['sprunk_can'] = {
    label = "Sprunk Can",
    weight = 330,
    stack = false,
    allowArmed = false,
    degrade = 1080,
},
['ecola_can'] = {
    label = "e-Cola Can",
    weight = 330,
    stack = false,
    allowArmed = false,
    degrade = 1080,
},
['junk_can'] = {
    label = "Junk Can",
    weight = 500,
    stack = false,
    allowArmed = false,
    degrade = 1080,
},
['patriot_beer'] = {
    label = "Patriot Beer",
    weight = 500,
    stack = false,
    allowArmed = false,
},
['logger_beer'] = {
    label = "Logger Beer",
    weight = 500,
    stack = false,
    allowArmed = false,
},
['piswasser_beer'] = {
    label = "Piswasser Beer",
    weight = 500,
    stack = false,
    allowArmed = false,
},
['themount_whiskey'] = {
    label = "The Mount Whiskey",
    weight = 750,
    stack = false,
    allowArmed = false,
},
['bleuterd_champagne'] = {
    label = "Champagne",
    weight = 750,
    stack = false,
    allowArmed = true
},
['bleuterd_champagne2'] = {
    label = "Champagne",
    weight = 750,
    stack = false,
    allowArmed = true
},
['vodka'] = {
    label = "Vodka",
    weight = 700,
    stack = false,
    allowArmed = true
},
['glass'] = {
    label = "Glass",
    weight = 300,
    stack = false,
    allowArmed = false,
},
['whisky_glass'] = {
    label = "Whisky Glass",
    weight = 400,
    stack = false,
    allowArmed = false,
},
['shot_glass'] = {
    label = "Shot Glass",
    weight = 180,
    stack = false,
    allowArmed = false,
},
['champ_flute'] = {
    label = "Champagne Flute",
    weight = 280,
    stack = false,
    allowArmed = false,
},
['lighter'] = {
    label = "Lighter",
    weight = 20,
    stack = true,
    allowArmed = false
},
['redwood_pack'] = {
    label = "Redwood Pack",
    weight = 100,
    stack = false,
    allowArmed = false
},
['cigarette'] = {
    label = "Cigarette",
    weight = 5,
    stack = true,
    allowArmed = false
},
['codeine'] = {
    label = "Codeine",
    weight = 100,
    stack = false,
    allowArmed = false
},
['joint_sd'] = {
    label = "Sour Diesel Joint",
    weight = 5,
    stack = true,
    allowArmed = false
},
['joint_nl'] = {
    label = "Northern Lights Joint",
    weight = 5,
    stack = true,
    allowArmed = false
},
['cocaine'] = {
    label = "Cocaine Bag",
    weight = 10,
    stack = true,
    allowArmed = false
},
['amphetamine'] = {
    label = "Amphetamine Bag",
    weight = 10,
    stack = true,
    allowArmed = false
},
['meth'] = {
    label = "Methamphetamine Bag",
    weight = 10,
    stack = true,
    allowArmed = false
},
['heroin'] = {
    label = "Heroin",
    weight = 10,
    stack = true,
    allowArmed = false
},
['heroin_syringe'] = {
    label = "Heroin Syringe",
    weight = 10,
    stack = false,
    allowArmed = false
},
['lsd'] = {
    label = "LSD",
    weight = 5,
    stack = false,
    allowArmed = false
},
['breathalyzer'] = {
    label = "Breathalyzer",
    weight = 420,
    stack = true,
    allowArmed = false
},
['drugtest_thc'] = {
    label = "Drug Test (THC)",
    weight = 150,
    stack = false,
    allowArmed = false
},
['drugtest_lsd'] = {
    label = "Drug Test (LSD)",
    weight = 150,
    stack = false,
    allowArmed = false
},
['drugtest_multi'] = {
    label = "Drug Test Multi",
    weight = 200,
    stack = false,
    allowArmed = false
},

Items for qb-inventory / origen_inventory

['sandwich'] = {
    name = 'sandwich',
    label = "Sandwich",
    description = "",
    weight = 80,
    type = "item",
    image = "sandwich.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['burger'] = {
    name = 'burger',
    label = "Burger",
    description = "",
    weight = 120,
    type = "item",
    image = "burger.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['hotdog'] = {
    name = 'hotdog',
    label = "Hot-Dog",
    description = "",
    weight = 100,
    type = "item",
    image = "hotdog.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['apple'] = {
    name = 'apple',
    label = "Apple",
    description = "",
    weight = 60,
    type = "item",
    image = "apple.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['water'] = {
    name = 'water',
    label = "Water",
    description = "",
    weight = 500,
    type = "item",
    image = "water.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['sprunk_can'] = {
    name = 'sprunk_can',
    label = "Sprunk Can",
    description = "",
    weight = 330,
    type = "item",
    image = "sprunk_can.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['ecola_can'] = {
    name = 'ecola_can',
    label = "e-Cola Can",
    description = "",
    weight = 330,
    type = "item",
    image = "ecola_can.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['junk_can'] = {
    name = 'junk_can',
    label = "Junk Can",
    description = "",
    weight = 500,
    type = "item",
    image = "junk_can.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['patriot_beer'] = {
    name = 'patriot_beer',
    label = "Patriot Beer",
    description = "",
    weight = 500,
    type = "item",
    image = "patriot_beer.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['logger_beer'] = {
    name = 'logger_beer',
    label = "Logger Beer",
    description = "",
    weight = 500,
    type = "item",
    image = "logger_beer.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['piswasser_beer'] = {
    name = 'piswasser_beer',
    label = "Piswasser Beer",
    description = "",
    weight = 500,
    type = "item",
    image = "piswasser_beer.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['themount_whiskey'] = {
    name = 'themount_whiskey',
    label = "The Mount Whiskey",
    description = "",
    weight = 750,
    type = "item",
    image = "themount_whiskey.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['bleuterd_champagne'] = {
    name = 'bleuterd_champagne',
    label = "Champagne",
    description = "",
    weight = 750,
    type = "item",
    image = "bleuterd_champagne.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['bleuterd_champagne2'] = {
    name = 'bleuterd_champagne2',
    label = "Champagne",
    description = "",
    weight = 750,
    type = "item",
    image = "bleuterd_champagne2.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['vodka'] = {
    name = 'vodka',
    label = "Vodka",
    description = "",
    weight = 700,
    type = "item",
    image = "vodka.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['glass'] = {
    name = 'glass',
    label = "Glass",
    description = "",
    weight = 300,
    type = "item",
    image = "glass.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['whisky_glass'] = {
    name = 'whisky_glass',
    label = "Whisky Glass",
    description = "",
    weight = 400,
    type = "item",
    image = "whisky_glass.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['shot_glass'] = {
    name = 'shot_glass',
    label = "Shot Glass",
    description = "",
    weight = 180,
    type = "item",
    image = "shot_glass.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['champ_flute'] = {
    name = 'champ_flute',
    label = "Champagne Flute",
    description = "",
    weight = 280,
    type = "item",
    image = "champ_flute.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['lighter'] = {
    name = 'lighter',
    label = "Lighter",
    description = "",
    weight = 20,
    type = "item",
    image = "lighter.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['redwood_pack'] = {
    name = 'redwood_pack',
    label = "Redwood Pack",
    description = "",
    weight = 100,
    type = "item",
    image = "redwood_pack.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['cigarette'] = {
    name = 'cigarette',
    label = "Cigarette",
    description = "",
    weight = 5,
    type = "item",
    image = "cigarette.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['codeine'] = {
    name = 'codeine',
    label = "Codeine",
    description = "",
    weight = 100,
    type = "item",
    image = "codeine.png",
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['joint_sd'] = {
    name = 'joint_sd',
    label = "Sour Diesel Joint",
    description = "",
    weight = 5,
    type = "item",
    image = "joint_sd.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['joint_nl'] = {
    name = 'joint_nl',
    label = "Northern Lights Joint",
    description = "",
    weight = 5,
    type = "item",
    image = "joint_nl.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['cocaine'] = {
    name = 'cocaine',
    label = "Cocaine Bag",
    description = "",
    weight = 10,
    type = "item",
    image = "cocaine.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['amphetamine'] = {
    name = 'amphetamine',
    label = "Amphetamine Bag",
    description = "",
    weight = 10,
    type = "item",
    image = "amphetamine.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['meth'] = {
    name = 'meth',
    label = "Methamphetamine Bag",
    description = "",
    weight = 10,
    type = "item",
    image = "meth.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['heroin'] = {
    name = 'heroin',
    label = "Heroin",
    description = "",
    weight = 10,
    type = "item",
    image = "heroin.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['heroin_syringe'] = {
    name = 'heroin_syringe',
    label = "Heroin Syringe",
    description = "",
    weight = 10,
    type = "item",
    image = "heroin_syringe.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['lsd'] = {
    name = 'lsd',
    label = "LSD",
    description = "",
    weight = 5,
    type = "item",
    image = "lsd.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['breathalyzer'] = {
    name = 'breathalyzer',
    label = "Breathalyzer",
    description = "",
    weight = 420,
    type = "item",
    image = "breathalyzer.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['drugtest_thc'] = {
    name = 'drugtest_thc',
    label = "Drug Test (THC)",
    description = "",
    weight = 150,
    type = "item",
    image = "drugtest_thc.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['drugtest_lsd'] = {
    name = 'drugtest_lsd',
    label = "Drug Test (LSD)",
    description = "",
    weight = 150,
    type = "item",
    image = "drugtest_lsd.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},
['drugtest_multi'] = {
    name = 'drugtest_multi',
    label = "Drug Test Multi",
    description = "",
    weight = 200,
    type = "item",
    image = "drugtest_multi.png",
    unique = false,
    useable = true,
    shouldClose = true,
    combinable = nil,
},

---

4. Remove Conflicting Resources

Before starting VMS Needs, make sure to remove or disable any resources that provide the same functionality.

Running multiple needs/status systems at the same time may cause conflicts, duplicated effects, or unexpected behavior.

Common resources that should be removed:

• esx_status

• esx_basicneeds

• qb-smallresources (consumables.lua file)

• Any custom hunger / thirst / stress / needs system

• Any standalone consumables resource that modifies player needs

⚠️ Additional Step for qb-core (Required)

You must remove the built-in hunger/thirst handling from qb-core to prevent conflicts with VMS Needs.

Remove the following code from: qb-core/client/loops.lua

CreateThread(function()
    while true do
        if LocalPlayer.state.isLoggedIn then
            if (QBCore.PlayerData.metadata['hunger'] <= 0 or QBCore.PlayerData.metadata['thirst'] <= 0) and not (QBCore.PlayerData.metadata['isdead'] or QBCore.PlayerData.metadata['inlaststand']) then
                local ped = PlayerPedId()
                local currentHealth = GetEntityHealth(ped)
                local decreaseThreshold = math.random(5, 10)
                SetEntityHealth(ped, currentHealth - decreaseThreshold)
            end
        end
        Wait(QBCore.Config.StatusInterval)
    end
end)

⚠️ Additional Step for qbx_core (Required)

You must remove the built-in hunger/thirst handling from qbx_core to prevent conflicts with VMS Needs.

Remove the following code from: qbx_core/client/loops.lua

CreateThread(function()
    local timeout = 1000 * statusInterval
    while true do
        Wait(timeout)

        if QBX.IsLoggedIn then
            if ((playerState.hunger or 0) <= 0 or (playerState.thirst or 0) <= 0) and not playerState.isDead then
                local currentHealth = GetEntityHealth(cache.ped)
                local decreaseThreshold = math.random(5, 10)
                SetEntityHealth(cache.ped, currentHealth - decreaseThreshold)
            end
        end
    end
end)

Remove the following code from: qbx_core/server/loops.lua

local function removeHungerAndThirst(src, player)
    local playerState = Player(src).state
    if not playerState.isLoggedIn then return end
    local newHunger = playerState.hunger - config.player.hungerRate
    local newThirst = playerState.thirst - config.player.thirstRate

    player.Functions.SetMetaData('thirst', newThirst)
    player.Functions.SetMetaData('hunger', newHunger)

    player.Functions.Save()
end

CreateThread(function()
    local interval = 60000 * config.updateInterval
    while true do
        Wait(interval)
        forEachPlayerStaggered(removeHungerAndThirst)
    end
end)

Important: VMS Needs is designed to fully replace these systems. Running them together is not supported.

---

6. Start Resource

To start a resource in your server.cfg, ensure that it begins after your framework has been initiated. For instance, if you are using a framework like es_extended, you should start resource after it, like so:

start [core] # For example, here is your framework (esx/qb-core)

# Here you run your other resources like esx_policejob etc.

# VMS Resources
start vms_needs

Ensure there are no syntax errors or incorrect paths in your server.cfg.