The script is fully functional as is, without requiring any modifications. However, for those who want to expand its capabilities, a complete integration allows for:
✅ Multiple Wrapping at Once
With full integration, players can wrap multiple Gift Boxes simultaneously, improving efficiency and user experience.
✅ Seamless Inventory System Integration
The script is designed to work with various inventory systems. By implementing additional metadata handling and export functions, it can seamlessly interact with different inventories, ensuring smooth item management.
🔹 Important Note:
These enhancements are optional and are only needed if you want to extend functionality.
This approach allows for greater adaptability while maintaining the script’s stability and usability in its default state.
📌 Integration Steps:
To integrate, refer to the documentation of your inventory system.
Pay close attention to the sections marked as "necessary for advanced integration" to ensure proper compatibility and implementation.
- Obtaining inventory
To ensure that the inventory is started and available you must go to the following path
In the GetInventory(..)function, You should place your inventory, followed by the returns
You can copy the following code and replace 'other-inventory' with the name of your inventory resource
function GetInventory()
if GetResourceState('ox_inventory') == 'started' then
return 'ox_inventory', true
elseif GetResourceState('qb-inventory') == 'started' then
return 'qb-inventory', true
elseif GetResourceState('other-inventory') == 'started' then
return 'other-inventory', true -- return the inventory name and true as available
else
return nil, false
end
end
-- @param source The player's source ID.
-- @param itemName The name of the item to give.
-- @param itemCount The quantity of the item to give.
-- @param metadata Additional item metadata (optional).
function GivePlayerItem(source, itemName, itemCount, metadata)
-- ox_inventory && qb-inventory compatibility
if inventory == 'ox_inventory' then
exports['ox_inventory']:AddItem(source, itemName, itemCount, metadata)
return
elseif inventory == 'qb-inventory' then
exports['qb-inventory']:AddItem(source, itemName, itemCount, false, metadata)
return
elseif inventory == 'other-inventory' then
exports['other-inventory']:AddItem(...) -- add your export
return
end
if Config.Framework == 'esx' then
local xPlayer = Framework.GetPlayerFromId(source)
xPlayer.addInventoryItem(itemName, itemCount)
elseif Config.Framework == 'qb-core' then
local Player = Framework.Functions.GetPlayer(source)
Player.Functions.AddItem(itemName, itemCount)
elseif Config.Framework == 'standalone' then
-- Custom Give player item if you are using your own framework
Framework.AddItemToPlayer(source, itemName, itemCount)
else
print("ERROR: Unknown framework in function GivePlayerItem.")
end
end
elseif inventory == 'other-inventory' then
exports['other-inventory']:AddItem(...) -- add your export
return -- ** @NOTE
end
-- @NOTE:
-- It is necessary to stop the code with a return
-- to prevent double item delivery
-- @param source The player's source ID.
-- @param itemName The name of the item to remove.
-- @param itemCount The quantity of the item to remove.
-- @param slot The inventory slot from which to remove the item (optional).
function RemovePlayerItem(source, itemName, itemCount, slot)
-- ox_inventory && qb-inventory compatibility
if inventory == 'ox_inventory' then
exports['ox_inventory']:RemoveItem(source, itemName, itemCount, false, slot)
return
elseif inventory == 'qb-inventory' then
local Player = Framework.Functions.GetPlayer(source)
if Player then
if slot then
Player.Functions.RemoveItem(itemName, itemCount, slot)
else
Player.Functions.RemoveItem(itemName, itemCount)
end
end
return
elseif inventory == 'other-inventory' then
exports['other-inventory']:RemoveItem(...) -- add your export
return
end
if Config.Framework == 'esx' then
local xPlayer = Framework.GetPlayerFromId(source)
xPlayer.removeInventoryItem(itemName, itemCount)
elseif Config.Framework == 'qb-core' then
local Player = Framework.Functions.GetPlayer(source)
Player.Functions.RemoveItem(itemName, itemCount)
elseif Config.Framework == 'standalone' then
-- Custom Remove player item if you are using your own framework
Framework.RemoveItemFromPlayer(source, itemName, itemCount) -- You need to implement this function
else
print("ERROR: Unknown framework in function RemovePlayerItem.")
end
end
elseif inventory == 'other-inventory' then
exports['other-inventory']:RemoveItem(...) -- add your export
return -- ** @NOTE
end
-- @NOTE:
-- It is necessary to stop the code with a return
-- to prevent double item removal
- UsePlayerItem
Ks_Gift_Packaging/Framework/sv_Custom.lua:
UsePlayerItem(itemName, useFunction)
itemName: string
useFunction: function
necessary for advanced integration
-- @param itemName The name of the item to register as usable.
-- @param useFunction The function to execute when the item is used.
function UsePlayerItem(itemName, useFunction)
-- ox_inventory && qb-inventory compatibility
if inventory == 'ox_inventory' then
-- Does nothing
return
elseif inventory == 'qb-inventory' then
Framework.Functions.CreateUseableItem(itemName, function(source, item)
useFunction(source, item)
end)
return
elseif inventory == 'other-inventory' then
-- Your RegisterUsableItem function for inventory compatibility
exports['other-inventory']:CreateUseableItem(itemName, function(source, item)
useFunction(source, item)
end)
return
end
if Config.Framework == 'esx' then
Framework.RegisterUsableItem(itemName, function(source)
useFunction(source)
end)
elseif Config.Framework == 'qb-core' then
Framework.Functions.CreateUseableItem(itemName, function(source, item)
useFunction(source, item)
end)
elseif Config.Framework == 'standalone' then
-- Custom Create Usable Item function if you are using your own framework
Framework.RegisterUsableItem(itemName, function(source)
useFunction(source)
end)
else
print("ERROR: Unknown framework in function UsePlayerItem.")
end
end
elseif inventory == 'other-inventory' then
-- Your RegisterUsableItem function for inventory compatibility
exports['other-inventory']:CreateUseableItem(itemName, function(source, item)
useFunction(source, item) -- -- @NOTE-1:
end)
return -- @NOTE-2:
end
-- @NOTE-1:
-- It is necessary to pass both `source` and `item` to the function
-- to ensure that the item usage logic receives the player's ID (`source`)
-- and the item data (`item`). This allows customization based on
-- item properties such as `item.name`, `item.count`, `item.metadata`, etc.
-- @NOTE-2:
-- It is necessary to stop the code with a return
-- to prevent duplicate item usage registration
Why is it necessary to inherit source and item in useFunction(source, item)?
Inheriting these parameters in useFunction(source, item) is essential for the following reasons:
The source parameter represents the player's ID on the server, allowing us to target the correct player when executing actions.
The item parameter contains essential details about the item in use. In this case, we need its metadata:
item.metadata → Additional data stored in the item, such as messages or unique attributes.
This ensures that item interactions work correctly and that any special properties assigned to an item can be properly accessed and used.
Where will we use the metadata of my object in use?
In this script, the metadata of the item is extracted and used in two main cases:
When a player uses a gift box (ks.GiftBox)
The script retrieves the item's metadata (item.info or item.metadata).
It then triggers the event 'ks-Gifts:server:InternGiftBoxes', passing the player's ID (source), the item name (giftBox), and its metadata.
This allows the server to process the gift box based on its specific properties.
UsePlayerItem(giftBox, function(source, item)
local metadata = (item and item.info) or (item and item.metadata) or nil
TriggerEvent('ks-Gifts:server:InternGiftBoxes', source, giftBox, metadata)
end)
When a player uses a gift card (ks.GiftCard)
The metadata is retrieved the same way.
If the metadata contains a message, it is sent to the client using 'ks-Gifts:client:OpenCard'.
If no message is found, the player receives a notification.
UsePlayerItem(ks.GiftCard, function(source, item)
local metadata = (item and item.info) or (item and item.metadata) or nil
if metadata and metadata.message then
local message = metadata.message
TriggerClientEvent('ks-Gifts:client:OpenCard', source, message)
else
TriggerClientEvent('ks-Gifts:Notification', source, 'NoMessage', 3000, 'error')
end
end)
THESE FUNCTIONS ARE IN:
Ks_Gift_Packaging/server/usable.lua:
if not Inventory_Compatible or inventory ~= 'ox_inventory' then
for _, giftBox in ipairs(ks.GiftBox) do
UsePlayerItem(giftBox, function(source, item)
local metadata = (item and item.info) or (item and item.metadata) or nil
TriggerEvent('ks-Gifts:server:InternGiftBoxes', source, giftBox, metadata)
end)
end
UsePlayerItem(ks.GiftCard, function(source, item)
local metadata = (item and item.info) or (item and item.metadata) or nil
if metadata and metadata.message then
local message = metadata.message
TriggerClientEvent('ks-Gifts:client:OpenCard', source, message)
else
TriggerClientEvent('ks-Gifts:Notification', source, 'NoMessage', 3000, 'error')
end
end)
end
This metadata retrieval is not necessary for ox_inventory, unless the inventory system has a export to fetch the metadata of the item in use.