Items and Weapons

Item definitions

Define normal items in data/items.lua.

['sandwich'] = {
    label = 'Sandwich',
    description = 'A fresh sandwich',
    weight = 250,
    stack = true,
    close = true,
    consume = 1,
    client = {
        image = 'sandwich.png',
        usetime = 2500,
        anim = 'eating',
        status = { hunger = 150000 },
        notification = 'You ate a sandwich',
    },
}

Common item fields

Field	Purpose
label	Display name.
description	Tooltip description.
weight	Weight per unit in grams.
stack	Whether equivalent instances share one slot. Defaults to true.
close	Whether using the item closes the inventory.
consume	Amount removed or durability consumed after use.
canThrow	Enables the Throw action when throwing is configured.
throwProp	World prop used for a thrown normal item.
client.image	Image filename under the configured image path.
client.dropprop	World prop for this item when it is alone in a ground drop; separate from throwProp.
client.usetime	Progress duration in milliseconds.
client.anim / client.prop	Named preset or inline animation/prop definition.
client.status	Status deltas applied after successful use.
client.event / client.export	Client integration called after use.
server.export	Server callback involved in using the item.
buttons	Custom item context-menu actions.

Consumption rules

• consume = 0 leaves the item untouched by the registry.
• consume >= 1 removes that many items after successful use.
• A value between 0 and 1 reduces durability.
• If consume is omitted, it always defaults to zero, including items with client.usetime or server.export. Set consume = 1 explicitly for items that should be removed after successful use.

Review this setting when migrating item definitions: a use animation or server callback does not imply automatic consumption.

Ground-drop props

Set client.dropprop on an item to choose its single-item ground-drop model. Item-specific props settle using gravity; the fallback Config.DropProp is placed upright. Multi-item drops, items without a suitable model, and invalid models use the fallback path. Config.DropProps and Config.DropMarker control prop/marker presentation. This is separate from the Throw action and its throwProp setting.

Item images

Put images in:

wasabi_inventory/ui/images/

The default filename is <itemname>.png. Override it with client.image.

Named animation presets

Add reusable animation and prop presets to data/animations.lua, then reference the key from client.anim or client.prop.

Backpacks

A backpack is a non-stackable item with backpack = true.

['small_backpack'] = {
    label = 'Small Backpack',
    weight = 1200,
    stack = false,
    backpack = true,
    slots = 5,
    maxWeight = 15000,
    model = 'p_michael_backpack_s',
    offset = {
        bone = 24818,
        pos = vec3(0.07, -0.11, -0.05),
        rot = vec3(0.0, 90.0, 175.0),
    },
    consume = 0,
}

Use either a model and offset, or a clothing component definition. Backpack capacity is capped by Config.BackpackMaxSlots.

Weapons, ammunition, and components

Define these in data/weapons.lua under the returned Weapons, Ammo, and Components tables. Lookups are by item name, so backend calls such as AddItem(source, 'WEAPON_PISTOL', 1) work as long as that name exists in the loaded data.

Weapons = {
    ['WEAPON_PISTOL'] = {
        label = 'Pistol',
        weight = 1100,
        durability = 0.1,
        ammoname = 'ammo-9',
    },
}

The shipped file is a Wasabi starter pack (common GTA weapon names with Wasabi defaults). To keep exact weights and durability from an existing ox_inventory install, replace or merge this file with your previous data/weapons.lua — see Installation.

The weapon engine supports inventory-owned equip state, ammunition metadata, durability, components, tints, unload/remove actions, and throwable weapons.

warning

Custom weapons must be assigned a server-side clip size in Config.WeaponClipSizes. Custom weapon/component combinations must also be added to Config.WeaponComponentCompatibility. Test both in a live FiveM runtime.