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.

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

Size

Defines the total quantity or capacity stored by the item.

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.

Smell Profile (Optional)

Assigns a smell profile to the item.

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.

Required Items (Optional)

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

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

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.

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

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.

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.

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.

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.

Attachments

Defines how a model is attached to a player bone.

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

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.

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

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.

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
    },
}

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

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

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

Removing statuses

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.

thirst = 45

Always adds 45.

thirst = {18, 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.

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

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.

giveItem = 'cigarette',

The pack’s size determines how many units remain.

Drug Test Category

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

testCategory = 'LSD',

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

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