> 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/guides/creating-a-custom-item.md).

# Creating a Custom Item

This guide explains how to create your own usable items and configure their behavior.

***

### 1. Create a new item

Every usable item must be registered inside `Config.Items`.\
The table key must match the item name registered in your inventory.

```lua
['my_item'] = {

}
```

### 2. Choose an Item Type

The `type` option defines the item category used by VMS Needs and other configurable systems, such as item accidents.

```lua
type = 'drink',
```

VMS Needs includes several default types, such as `food`, `drink`, `glass`, `drug`, `cig`, `cigarette_pack`, `breathalyzer`, and `drugtest`.

These values are not restricted - you can create your own item types when implementing custom behavior.

### 3. Choose a Behavior (optional)

The `behavior` option assigns custom interaction logic to the item.

```lua
behavior = 'smoking',
```

Simple items such as standard food and drinks usually do not require a behavior. Advanced items, including cigarettes, powder drugs, syringes, breathalyzers, and drug tests, use behavior files to control their interaction flow.

Built-in behaviors are located in: **shared/behaviors/**

Behavior files are open and can be modified or used as templates for completely custom item interactions. The selected behavior determines which model, attachment, animation, and particle keys are required.

### 4. Configure the Item Properties

<details>

<summary>Size</summary>

Defines the total quantity or capacity stored by the item.

```lua
size = 500,
```

The unit depends on the item:

* drinks and glasses usually use milliliters,
* food can use grams or a custom portion size,
* cigarettes and joints commonly use a durability value,
* single-use drugs may use `1`.

</details>

<details>

<summary>Smell Profile (Optional)</summary>

Assigns a smell profile to the item.

```lua
smellProfile = 'alcohol',
```

The value must match a profile defined in `Config.SmellProfiles`. When liquids are mixed, smell detection is calculated using their contribution to the total composition.

</details>

<details>

<summary>Required Items (Optional)</summary>

Defines additional inventory items required to use or prepare the item.

```lua
requiredItems = {
    {name = 'lighter', quantity = 1, remove = false},
}
```

<table><thead><tr><th width="180.3636474609375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Inventory item name.</td></tr><tr><td><code>quantity</code></td><td>Required amount.</td></tr><tr><td><code>remove</code></td><td>Whether the required item is removed when used.</td></tr></tbody></table>

Requirements are validated before the interaction begins.

</details>

<details>

<summary>Player Restrictions</summary>

Defines which player actions are disabled while the item is active.

```lua
disableRun = true,
disableJump = true,
disableMelee = true,
disableAsDriver = true,
disableInVehicle = true,
```

<table><thead><tr><th width="180.3636474609375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>disableRun</code></td><td>Prevents sprinting.</td></tr><tr><td><code>disableJump</code></td><td>Prevents jumping.</td></tr><tr><td><code>disableMelee</code></td><td>Prevents melee attacks.</td></tr><tr><td><code>disableAsDriver</code></td><td>Prevents use while driving.</td></tr><tr><td><code>disableInVehicle</code></td><td>Prevents use inside any vehicle.</td></tr></tbody></table>

</details>

<details>

<summary>Models</summary>

Defines the GTA models used during the interaction.

```lua
models = {
    default = 'prop_ld_flow_bottle'
},
```

The required keys depend on the selected behavior. A simple item may only use `default`, while advanced behaviors can require entries such as `lighter`, `powder`, `line`, `card`, `syringe`, or custom nested model states.

```lua
models = {
    [0] = 'prop_cs_shot_glass',
    [5] = 'ba_prop_battle_shot_glass_01',
}
```

Numeric keys represent the minimum fill or usage percentage at which a model becomes active.

```lua
lit = {
    [0] = 'vms_cigarette_1',
    [30] = 'vms_cigarette_2',
    [60] = 'vms_cigarette_3',
    [80] = 'prop_cs_ciggy_01b'
}
```

This allows the visible model to change as the item is consumed.

</details>

<details>

<summary>Attachments</summary>

Defines how a model is attached to a player bone.

```lua
attaches = {
    hand = {
        bone = 57005,
        offset = vector3(0.124, 0.024, -0.023),
        rotation = vector3(-87.04, 0.0, -10.24),
    },
},
```

<table><thead><tr><th width="180.3636474609375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>bone</code></td><td>GTA ped bone ID.</td></tr><tr><td><code>offset</code></td><td>Position offset relative to the bone.</td></tr><tr><td><code>rotation</code></td><td>Rotation relative to the bone.</td></tr></tbody></table>

Attachment names are referenced by behaviors and can be freely extended in custom behavior files.

</details>

<details>

<summary>Animations</summary>

Defines animations used at different stages of the interaction.

```lua
animation = {
    idle = {
        dictionary = 'amb@code_human_wander_drinking@male@base',
        name = 'static',
        duration = -1,
        flag = 51
    },
}
```

<table><thead><tr><th width="180.3636474609375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>dictionary</code></td><td>Animation dictionary.</td></tr><tr><td><code>name</code></td><td>Animation clip name.</td></tr><tr><td><code>duration</code></td><td>Duration in milliseconds. Use <code>-1</code> for looping animations.</td></tr><tr><td><code>flag</code></td><td>GTA animation flag.</td></tr></tbody></table>

</details>

<details>

<summary>Particles (Optional)</summary>

Defines named particle effects available to the behavior.

```lua
particles = {
    fire = {
        dictionary = 'scr_fm_mp_missioncreator',
        name = 'scr_sh_lighter_flame',
        rotation = vector3(0.0, 0.0, 0.0),
        scale = 1.5,
        time = 1500
    },
}
```

<table><thead><tr><th width="180.3636474609375">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>dictionary</code></td><td>Particle asset dictionary.</td></tr><tr><td><code>name</code></td><td>Particle effect name.</td></tr><tr><td><code>boneIndex</code></td><td>Optional ped bone used for attachment.</td></tr><tr><td><code>rotation</code></td><td>Local particle rotation.</td></tr><tr><td><code>scale</code></td><td>Particle size.</td></tr><tr><td><code>time</code></td><td>Duration in milliseconds.</td></tr></tbody></table>

Particle entry names are referenced by the behavior. Do not rename built-in entries unless the behavior is updated accordingly.

</details>

<details>

<summary>Consumption</summary>

Defines how much of the item is consumed during each use and how player statuses are modified.

#### Bite size

```lua
consume = {
    bite = {
        minimum = 40,
        maximum = 90
    },
}
```

Each use consumes a random amount between `minimum` and `maximum`, limited by the item's remaining size.

#### Adding statuses

```lua
add = {
    thirst = {18, 45},
    drunk = {0.6, 1.2},
}
```

#### Removing statuses

```lua
remove = {
    stress = {1.6, 3.5},
}
```

Numeric values apply a fixed status change.\
A `{minimum, maximum}` range is scaled according to the consumed amount relative to `consume.bite.maximum`.

```lua
thirst = 45
```

Always adds 45.

```lua
thirst = {18, 45}
```

Produces a proportional value between 18 and 45, depending on the amount consumed.

</details>

<details>

<summary>Allowed Drinks (Glass Items Only)</summary>

Defines which configured drinks can be poured into the glass.

```lua
allowedDrinks = {
    water = true,
    sprunk_can = true,
    patriot_beer = true,
}
```

Each key must match an item name in `Config.Items`.

</details>

<details>

<summary>Give Item (Pack Items)</summary>

Defines the item received when taking a unit from a pack.

```lua
giveItem = 'cigarette',
```

The pack’s `size` determines how many units remain.

</details>

<details>

<summary>Drug Test Category</summary>

Assigns a test category to a single-category drug test.

```lua
testCategory = 'LSD',
```

The value must match a category defined in `Config.DrugTests.Categories`.

</details>

### 5. Behavior-Specific Properties

{% hint style="info" %}
**Important:** Some properties inside `models`, `attaches`, `animation`, and `particles` are behavior-specific. Always use an existing item with the same behavior as your starting template. When creating a custom behavior, you decide which keys are required and how they are used.
{% endhint %}

### 6. Complete Example

{% code expandable="true" %}

```lua
['my_energy_drink'] = {
    type = 'drink',
    smellProfile = 'sweet',

    size = 330,

    disableRun = true,
    disableJump = true,
    disableMelee = true,
    disableAsDriver = true,
    disableInVehicle = true,

    models = {
        default = 'prop_ecola_can'
    },

    attaches = {
        hand = {
            bone = 57005,
            offset = vector3(0.12, 0.02, -0.02),
            rotation = vector3(-87.0, 0.0, -10.0),
        },
    },

    animation = {
        idle = {
            dictionary = 'amb@code_human_wander_drinking@male@base',
            name = 'static',
            duration = -1,
            flag = 51
        },
        bite = {
            dictionary = 'amb@code_human_wander_drinking_fat@male@idle_a',
            name = 'idle_c',
            duration = 2000,
            flag = 51
        },
    },

    consume = {
        bite = {
            minimum = 30,
            maximum = 60
        },
        add = {
            thirst = {12, 28},
        },
        remove = {
            stress = {0, 1},
        },
    }
}
```

{% endcode %}