Integration

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

Ks_Gift_Packaging/Framework/sh_Custom.lua:GetInventory(..)

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

- GivePlayerItem

Ks_Gift_Packaging/Framework/sv_Custom.lua:

GivePlayerItem(source, itemName, itemCount, metadata)

• source: number

• itemName: string

• itemCount: number

• metadata: table

  • necessary for advanced integration

-- @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

- RemovePlayerItem

Ks_Gift_Packaging/Framework/sv_Custom.lua:

RemovePlayerItem(source, itemName, itemCount, slot)

• source: number

• itemName: string

• itemCount: number

• slot: number

  • necessary for advanced integration

-- @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:

1. 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)

1. 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.