How to Create an Item (QBCore Framework)

Welcome to this step-by-step tutorial on how to create a custom item in QBCore, a popular framework for FiveM roleplay servers. This guide will walk you through the entire process, from defining the item in shared.lua to creating an icon for your inventory. Let’s get started!

Introduction

Custom items enhance the roleplay experience by adding unique elements to your server. Whether you’re introducing new food, weapons, or miscellaneous objects, this guide will help you integrate them seamlessly into your QBCore server.

Understanding QBCore’s Item System

In QBCore, items are defined in a shared Lua file accessible by both the server and client. Each item has specific attributes like name, label, weight, type, image, and more. Understanding these attributes is crucial for creating functional and balanced items.

Creating a New Item in shared.lua

Locating the shared.lua File

The shared.lua file is where all the item definitions are stored. You can find it in the following directory:

[qb] > qb-core > shared > items.lua

Note: Some versions may have the file named shared.lua or items.lua.

Item Definition Structure

An item in QBCore is defined using a Lua table with specific keys. Here’s the general structure:

["itemname"] = {
    ["name"] = "itemname",
    ["label"] = "Item Label",
    ["weight"] = 0,
    ["type"] = "item",
    ["image"] = "itemimage.png",
    ["unique"] = false,
    ["useable"] = true,
    ["shouldClose"] = true,
    ["combinable"] = nil,
    ["description"] = "Item Description"
},

• name: Identifier used in scripts.
• label: Display name in the inventory.
• weight: Item weight (set to 0 if not used).
• type: Usually set to "item".
• image: Filename of the item’s icon.
• unique: true if the item is unique (cannot stack).
• useable: true if the item can be used.
• shouldClose: true to close inventory upon use.
• combinable: Defines if the item can be combined with others.
• description: A brief description of the item.

Adding Your Custom Item

1. Open items.lua or shared.lua:Use a text editor like Visual Studio Code or Notepad++ to open the file.
2. Add Your Item Definition:Insert your item definition within the existing items. For example:luaCode kopieren["energy_drink"] = { ["name"] = "energy_drink", ["label"] = "Energy Drink", ["weight"] = 500, ["type"] = "item", ["image"] = "energy_drink.png", ["unique"] = false, ["useable"] = true, ["shouldClose"] = true, ["combinable"] = nil, ["description"] = "A can of refreshing energy drink." },
   • Ensure that your item name ("energy_drink") is unique and uses underscores instead of spaces.
   • The image file ("energy_drink.png") should match the icon you’ll add later.
3. Save the File:After adding your item, save the items.lua or shared.lua file.

Adding the Item Icon to the Inventory UI

Finding or Creating an Icon

Using Existing Images

• Online Resources:
  • Flaticon
  • IconFinder
  • OpenGameArt
  Ensure you have the right to use the images, considering licensing.

Creating Your Own Icon

• Graphic Design Tools:
  • Adobe Photoshop
  • GIMP (free alternative)
  • Canva (online tool)
• Tips:
  • Use a transparent background (PNG format).
  • Keep the design consistent with existing icons.

Supported Image Formats and Sizes

• Format: PNG is recommended for transparency support.
• Size: Typically 64×64 pixels, but check existing item icons for consistency.

Placing the Icon in the Correct Directory

1. Navigate to the Inventory UI Folder:cssCode kopieren[qb] > qb-inventory > html > images
2. Add Your Icon:
   • Place your icon image (e.g., energy_drink.png) into the images folder.
   • Ensure the filename matches the "image" field in your item definition.
3. Update Resource:
   • If your server is running, you may need to restart the qb-inventory resource or restart the server entirely.

Testing Your New Item

1. Start the Server:Ensure your server is running without errors.
2. Give Yourself the Item:Use the in-game console or an admin menu to give yourself the item:bashCode kopieren/giveitem [YourPlayerID] energy_drink 1
3. Check the Inventory:
   • Open your inventory.
   • Verify that the item appears with the correct icon, label, and description.
4. Use the Item:
   • Attempt to use the item if it’s usable.
   • Ensure it behaves as expected.

Common Issues and Troubleshooting

• Item Not Appearing:
  • Double-check the item name and ensure it’s correctly added to items.lua.
  • Verify the image file is in the correct directory and matches the name in the item definition.
• Icon Not Displaying:
  • Ensure the image file is in PNG format and placed in the images folder.
  • Confirm the filename matches exactly, including case sensitivity.
• Errors on Server Start:
  • Check the server console for error messages.
  • Ensure there are no syntax errors in items.lua (e.g., missing commas or brackets).

Conclusion

Creating custom items in QBCore enhances your server’s uniqueness and player experience. By following this guide, you should now be able to add new items, assign icons, and troubleshoot common issues.