For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

['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.

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.

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

Size

Defines the total quantity or capacity stored by the item.

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.

Smell Profile (Optional)

Assigns a smell profile to the item.

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.

Required Items (Optional)

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

Option
Description

name

Inventory item name.

quantity

Required amount.

remove

Whether the required item is removed when used.

Requirements are validated before the interaction begins.

Player Restrictions

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

Option
Description

disableRun

Prevents sprinting.

disableJump

Prevents jumping.

disableMelee

Prevents melee attacks.

disableAsDriver

Prevents use while driving.

disableInVehicle

Prevents use inside any vehicle.

Models

Defines the GTA models used during the interaction.

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.

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

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

Attachments

Defines how a model is attached to a player bone.

Option
Description

bone

GTA ped bone ID.

offset

Position offset relative to the bone.

rotation

Rotation relative to the bone.

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

Animations

Defines animations used at different stages of the interaction.

Option
Description

dictionary

Animation dictionary.

name

Animation clip name.

duration

Duration in milliseconds. Use -1 for looping animations.

flag

GTA animation flag.

Particles (Optional)

Defines named particle effects available to the behavior.

Option
Description

dictionary

Particle asset dictionary.

name

Particle effect name.

boneIndex

Optional ped bone used for attachment.

rotation

Local particle rotation.

scale

Particle size.

time

Duration in milliseconds.

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

Consumption

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

Bite size

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

Adding statuses

Removing statuses

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

Always adds 45.

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

Allowed Drinks (Glass Items Only)

Defines which configured drinks can be poured into the glass.

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

Give Item (Pack Items)

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

The pack’s size determines how many units remain.

Drug Test Category

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

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

5. Behavior-Specific Properties

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.

6. Complete Example

Last updated