Adding Items & Recipes

Adding Items & Recipes

An item

data/items.lua:

lockpick = {
    label       = 'Lockpick',
    weight      = 180,
    stack       = 5,
    category    = 'tool',
    rarity      = 'uncommon',
    description = 'Opens what was not meant to be opened.',
    usable      = true,
},

Then drop ui/images/lockpick.png in. Restart the resource. The admin panel's Definitions tab changes an existing item live, with no restart, but a new item starts in this file.

Making it do something

Built-in effects cover food, drink and medical:

burger = {
    useTime = 2500,
    effect  = { hunger = 35, anim = 'eat' },
}

One item is one use. portions = 4 makes it four, but only with Config.Portions.enabled = true; it is off by default, as in ox_inventory.

Anything else gets a handler:

exports.aty_inventory:RegisterUsable('lockpick', function(src, info)
    TriggerClientEvent('my_lockpicking:start', src, info.slot)
end)

A usable item is spent when it is used unless its definition says consume = false — a lockpick that should survive the attempt needs it.

examples/usable_handler.lua is a complete worked example, including how to answer cancellation properly.

A recipe

data/recipes.lua:

{
    id          = 'lockpick',
    ingredients = {
        { item = 'scrap',   count = 2 },
        { item = 'plastic', count = 1 },
    },
    results = { { item = 'lockpick', count = 1 } },
    time    = 2500,
},

A recipe lists at least two ingredients; dropping any one of them onto any other starts it. Mark an ingredient consume = false to make it a tool — required but not spent. time is how long the hands are busy: a recipe that names none takes 3000 ms, and 0 is instant.

Importing framework items

Items defined in QBCore or ESX already work — they are read through the bridge. To make this resource own them instead:

invmigrate items          dry run — shows what would be written
invmigrate items write    writes them into data/items.generated.lua

Add data/items.generated.lua to shared_scripts in fxmanifest.lua, after data/items.lua, then refresh and restart; an item defined in data/items.lua wins over a generated one. After that the catalogue no longer depends on the framework being up.

Checking your work

invdoctor

reports items with no image, items whose labels are confusable with each other, and shops or loot tables naming items that do not exist. A recipe naming an unknown item is skipped at start, and the console says which one and why.