Documentation

Exports & Events

All exports and events available to integrate this resource into others.

Types & Classes

All types & classes can be found in types.lua.

Suggestions?

If you wish to have any exports and or events added, please head over to our Discord and create a suggestion post. We are happy to allow for easier integration within other resources.

#Client Exports

#Is Current Empty

Returns if the current item you are holding is empty or not. Will also return false if you are not holding any item.

Example:

lua
---@return boolean
local isEmpty = exports["zyke_consumables"]:IsCurrentItemEmpty()

#Has Item Equipped

Returns if you currently have an item.

Example:

lua
---@return boolean
local hasItem = exports["zyke_consumables"]:HasItemEquipped()

#Is Occupied

Returns if you are currently occupied with any action within our script. Placement, consuming, grabbing item etc. If you are using the script and not idling it, you are most likely labeled as occupied.

If you are ever struggling with this, you can enable debug mode and it will explicitly tell you what is making you occupied.

Example:

lua
---@return boolean
local isOccupied = exports["zyke_consumables"]:IsOccupied()

#Get Equipped Item Metadata

Returns the cached metadata for the item you have equipped. You can find guaranteed values in zyke_consumables/types.lua, along with all of the metadata that already existed on the item before you equipped it.

Example:

lua
---@return table | nil
local metadata = exports["zyke_consumables"]:GetCurrentMetadata()

#Force Item Unequip

Forcefully unequips your item into your inventory if you have one equipped. Still performs the interaction animations & delays. This does wait for all of the interactions to finish before before you can proceed.

This will skip the check for the setting autoPourDrinkOnGround and automatically do it if needed.

Example:

lua
exports["zyke_consumables"]:ForceUnequip()

#Is Consuming

Check if you are currently consuming.

Example:

lua
---@return boolean
local isConsuming = exports["zyke_consumables"]:IsConsuming()

#Client Events

#Personal Setting Changed (Catch)

When you change any of your personal settings, this is triggered.

Example:

lua
---@param setting string
---@param value string | boolean
RegisterNetEvent("zyke_consumables:OnPersonalSettingChanged", function(setting, value)
    -- Perform any action in here
end)

#World Item Created (Catch)

When someone places an item, this is triggered. It does not track if you are in render, this will trigger for all world items on creation.

Example:

lua
---@param activeItemId string
---@param data table
RegisterNetEvent("zyke_consumables:WorldItemCreated", function(activeItemId, data)
    -- Perform any action in here
end)

#World Item Removed (Catch)

When someone removes an item, this is triggered. It does not track if you are in render, this will trigger for all world items on removal.

Example:

lua
---@param activeItemId string
---@param netId integer
RegisterNetEvent("zyke_consumables:WorldItemRemoved", function(activeItemId, netId)
    -- Perform any action in here
end)

#Occupied Changed (Catch)

Triggered on your client whenever your occupied state flips, mirroring the IsOccupied export. Only sent to the player whose state changed, and only when the value actually changes. Also available as the zyke_consumables:occupied state bag.

Example:

lua
---@param plyId integer @Your own server id
---@param occupied boolean @New occupied state
RegisterNetEvent("zyke_consumables:OnOccupiedChanged", function(plyId, occupied)
    -- Perform any action in here
end)

#Server Exports

#Is Current Empty

Returns if the current item you are holding is empty or not. Will also return false if you are not holding any item.

Example:

lua
---@param plyId integer
---@return boolean
local isEmpty = exports["zyke_consumables"]:IsCurrentItemEmpty(plyId)

#Has Item Equipped

Returns if you currently have an item.

Example:

lua
---@param plyId integer
---@return boolean
local hasItem = exports["zyke_consumables"]:HasItemEquipped(plyId)

#Is Occupied

Returns if you are currently occupied with any action within our script. Placement, consuming, grabbing item etc. If you are using the script and not idling it, you are most likely labeled as occupied.

If you are ever struggling with this, you can enable debug mode and it will explicitly tell you what is making you occupied.

Example:

lua
---@param plyId integer
---@return boolean
local isOccupied = exports["zyke_consumables"]:IsOccupied(plyId)

#Get Equipped Item Metadata

Returns the cached metadata for the item you have equipped. You can find guaranteed values in zyke_consumables/types.lua, along with all of the metadata that already existed on the item before.

Example:

lua
---@param plyId integer
---@return table | nil
local metadata = exports["zyke_consumables"]:GetCurrentMetadata(plyId)

#Force Item Unequip

Forcefully unequips your item into your inventory if you have one equipped. Still performs the interaction animations & delays. This does wait for all of the interactions to finish before before you can proceed.

This will skip the check for the setting autoPourDrinkOnGround and automatically do it if needed.

Example:

lua
---@param plyId integer
exports["zyke_consumables"]:ForceUnequip(plyId)

#Add To Current Item

Add amount to the current item of the target. This is limited to direct consumption-reward items.

Example:

lua
---@param plyId integer
---@param amount number
---@param valueType? "amount" | "percentage" @Default "amount"
---@return boolean
local success = exports["zyke_consumables"]:AddToCurrentItem(plyId, amount, valueType)

#Give Ingredient

Gives an ingredient, and allows you to configure the metadata easily in one go.

Example:

lua
---@param plyId integer
---@param name string @Item name
---@param amount? integer @Default 1
---@param quality? number @Default 100.0
exports["zyke_consumables"]:GiveIngredient(plyId, name, amount, quality)

#Add Item

Gives a consumable item.

This export will be replaced with specifics for consumption-reward-based & ingredient-based.

Example:

lua
---@param plyId integer
---@param itemIdentifier string @item id in settings or item name
---@param amount? integer @Default 1
---@param activeItemId? string @If the metadata is currently cached, most likely won't use this
---@param metadataIngredients? MetadataIngredient[] @If item is ingredient-based, pass in the ingredients you want, see types.lua
---@param quality? number @If item is direct consumption rewards, this is the quality
exports["zyke_consumables"]:AddItem(plyId, itemIdentifier, amount, activeItemId, metadataIngredients, quality)

#Craft Item

Crafts an ingredient-based consumable item. Do keep in mind that the ingredients you input will be added on top of the base ingredient configuration.

Example:

lua
---@param plyId integer
---@param itemIdentifier string @item id or item name
---@param ingredients? MetadataIngredient[] | {name: string, quality: number}[] @If none provided, it will just have the base items
---@param requireIngredients? boolean @If enabled, it will check & require the items, along with removing them
---@return boolean
local success = exports["zyke_consumables"]:CraftItem(plyId, itemIdentifier, ingredients, 


Example:

lua
-- This will craft a burger with the following ingredient list
-- You can also add in quality, but having none in here will default it to 100.0
-- This export is for demonstration purposes, and won't require any items in your
-- inventory because of the `requireIngredients` set as false
exports["zyke_consumables"]:CraftItem(plyId, "burger", {
    {name = "burger_bun_top", quality = 87.4}, -- Precise quality example
    {name = "pickles"},
    {name = "lettuce"},
    {name = "burger_patty"},
    {name = "burger_patty"},
    {name = "burger_patty"},
    {name = "cheese"},
    {name = "burger_patty"},
    {name = "ketchup"},
    {name = "burger_bun_bottom"},
}, false)

-- Example command if you want to test this out
-- Make sure that you have these items configured already
-- Check our guide if you need more assistance
RegisterCommand("craft_basic_item", function(source, args)
    local plyId = source

    exports["zyke_consumables"]:CraftItem(plyId, "burger", {
        {name = "burger_bun_top"},
        {name = "pickles"},
        {name = "lettuce"},
        {name = "burger_patty"},
        {name = "burger_patty"},
        {name = "burger_patty"},
        {name = "cheese"},
        {name = "burger_patty"},
        {name = "ketchup"},
        {name = "burger_bun_bottom"},
    }, false)
end, false)

#Is Consuming

Check if the target player is currently consuming.

Example:

lua
---@param plyId integer
---@return boolean
local isConsuming = exports["zyke_consumables"]:IsConsuming(plyId)

#Server Events

#Occupied Changed (Catch)

Triggered on the server whenever a player's occupied state flips, mirroring the IsOccupied export. Only triggered when the value actually changes. This is a server-side event, so catch it with AddEventHandler. Also available as the zyke_consumables:occupied state bag.

Example:

lua
---@param plyId integer @Server id of the player whose state changed
---@param occupied boolean @New occupied state
AddEventHandler("zyke_consumables:OnOccupiedChanged", function(plyId, occupied)
    -- Perform any action in here
end)

#State Bags

State Bag Change Handlers

All handlers below receive the standard FiveM arguments, typed as:

lua
---@param bagName string @"player:<serverId>"
---@param key string @State bag key, e.g. "zyke_consumables:occupied"
---@param value any @New value, typed per state bag below
---@param reserved integer @Unused, always 0
---@param replicated boolean @Whether the change came from the other side (client <-> server)

The handler runs before the new value is stored, so reading the state bag inside it returns the old value. Use the value argument instead.

#Occupied (Catch)

Replicated player state bag zyke_consumables:occupied, set by the server and mirroring the IsOccupied export. Unlike zyke_consumables:interacting, this also covers holding an equipped item. It is refreshed whenever the interacting state changes, and only written when the value actually changes, at the same time as the zyke_consumables:OnOccupiedChanged events.

The value is nil until it has been set for the first time, so compare with == true rather than relying on it being a boolean.

Type:

lua
---@alias ConsumablesOccupiedState boolean | nil @nil until first set, treat as false

Client Example:

lua
local bagName = ("player:%s"):format(GetPlayerServerId(PlayerId()))

---@param value ConsumablesOccupiedState
AddStateBagChangeHandler("zyke_consumables:occupied", bagName, function(_, _, value)
    local isOccupied = value == true
    -- Perform any action in here
end)

-- Or read it directly
---@type boolean
local isOccupied = LocalPlayer.state["zyke_consumables:occupied"] == true

Server Example:

lua
---@param bagName string
---@param value ConsumablesOccupiedState
AddStateBagChangeHandler("zyke_consumables:occupied", nil, function(bagName, _, value)
    local plyId = GetPlayerFromStateBagName(bagName)
    if (plyId == 0) then return end

    local isOccupied = value == true
    -- Perform any action in here
end)

-- Or read it directly
---@type boolean
local isOccupied = Player(plyId).state["zyke_consumables:occupied"] == true

#Interacting (Catch)

Replicated player state bag zyke_consumables:interacting, updated whenever you start or finish a short interaction (equipping, unequipping, opening, pouring, using/placing a pack, preparing a throw). The value is a table of active interactions, for example { equippingItem = true }, so you can react to specific ones only, such as checking value.pouringItem.

Holding an equipped item is not included, use HasItemEquipped or the zyke_consumables:occupied state bag for that.

Type:

lua
---@alias ConsumablesInteraction string @Interaction key, e.g. "equippingItem", "pouringItem"
---@alias ConsumablesInteractingState table<ConsumablesInteraction, true> | nil @Active interactions, nil or empty when idle

Client Example:

lua
local bagName = ("player:%s"):format(GetPlayerServerId(PlayerId()))

---@param value ConsumablesInteractingState
AddStateBagChangeHandler("zyke_consumables:interacting", bagName, function(_, _, value)
    ---@type boolean
    local isBusy = value ~= nil and next(value) ~= nil

    ---@type boolean
    local isPouring = value ~= nil and value.pouringItem == true
    -- Perform any action in here
end)

-- Or read it directly
---@type ConsumablesInteractingState
local state = LocalPlayer.state["zyke_consumables:interacting"]

Server Example:

lua
---@param bagName string
---@param value ConsumablesInteractingState
AddStateBagChangeHandler("zyke_consumables:interacting", nil, function(bagName, _, value)
    local plyId = GetPlayerFromStateBagName(bagName)
    if (plyId == 0) then return end

    ---@type boolean
    local isBusy = value ~= nil and next(value) ~= nil
    -- Perform any action in here
end)

-- Or read it directly
---@type ConsumablesInteractingState
local state = Player(plyId).state["zyke_consumables:interacting"]