> For the complete documentation index, see [llms.txt](https://docs.vames-store.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vames-store.com/assets/vms_needs/installation.md).

# Installation

## 1. Download Resource

Download the purchased resource from [**CFX Portal**](https://portal.cfx.re/assets/granted-assets) - 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**.

{% hint style="warning" %}

## 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.**](/helpful/basic-server-knowledge/how-to-import-sql-to-database.md)
{% endhint %}

<details>

<summary>Database for ESX</summary>

```sql
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;
```

</details>

<details>

<summary>Database for QB-Core</summary>

```sql
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;
```

</details>

***

## 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.

<details>

<summary>Items for ox_inventory</summary>

{% code expandable="true" %}

```lua
['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
},
```

{% endcode %}

</details>

<details>

<summary>Items for qb-inventory / origen_inventory</summary>

{% code expandable="true" %}

```lua
['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,
},
```

{% endcode %}

</details>

***

## 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` *(*&#x63;onsumables.lua fil&#x65;*)*
* Any custom hunger / thirst / stress / needs system
* Any standalone consumables resource that modifies player needs

<details>

<summary><strong>⚠️  Additional Step for qb-core (Required)</strong></summary>

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`&#x20;

```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)
```

</details>

<details>

<summary><strong>⚠️ Additional Step for qbx_core (Required)</strong></summary>

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`&#x20;

```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`&#x20;

```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)
```

</details>

{% hint style="warning" %}
**Important:**\
VMS Needs is designed to fully replace these systems. Running them together is **not supported**.
{% endhint %}

***

## 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:

```python
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`.