🛠️ Phase 1: The Foundation (Core Installation)

Before touching any inventory scripts, you must ensure the weapon itself is properly added to your server. This applies to all frameworks.

1. Structure Your Resource

Create a new folder in your resources directory, for example my_custom_weapon. Inside, you need:

• A stream folder containing your weapon files (.ytd, .ydr, .yft, etc.)
• A fxmanifest.lua file
• An optional meta folder for handling damage, recoil, and audio

2. Configure fxmanifest.lua

Your manifest tells FiveM how to load the files. A standard setup looks like this:

fx_version 'cerulean'
game 'gta5'

files {
    'meta/*.meta',
}

data_file 'WEAPONINFO_FILE_PATCH' 'meta/weapons.meta'

3. Start the Resource

Add ensure my_custom_weapon to your server.cfg file. Restart your server and check the console for any errors.

📦 Phase 2: Registering Weapons in Your Inventory

Once the weapon is streaming, you need to tell your inventory system that this item exists. Each inventory handles this differently.

1. Ox Inventory

File Location: ox_inventory/data/items.lua or weapons.lua in some versions.

['WEAPON_GLOCK17'] = {
label = 'Glock 17',
weight = 1000,
durability = 0.03,
ammoname = 'ammo-9',
stack = false,
close = true,
},

Pro Tip: For attachments, map the weapon hash to the attachment item in the client section of the attachment definition.

2. QB-Core

QB-Core requires registering the weapon in three places for full functionality using the default systems.

Step A: Shared Items - qb-core/shared/items.lua

['weapon_glock17'] = {
name = 'weapon_glock17',
label = 'Glock 17',
weight = 1000,
type = 'weapon',
ammotype = 'AMMO_PISTOL',
image = 'weapon_glock17.png',
unique = true,
useable = false,
description = 'A custom pistol'
},

Step B: Shared Weapons - qb-core/shared/weapons.lua

[`weapon_glock17`] = {
name = 'weapon_glock17',
label = 'Glock 17',
weapontype = 'Pistol',
ammotype = 'AMMO_PISTOL',
damagereason = 'Pistoled'
},

Step C: Weapon Config - qb-weapons/config.lua. If you want attachments to work, add your weapon to the WeaponAttachments table manually.

3. ESX

File Location: es_extended/config.weapons.lua

{
name = 'WEAPON_GLOCK17',
label = _U('weapon_glock17'),
ammo = { label = _U('ammo_rounds'), hash = `AMMO_PISTOL` },
components = {}
},

If you are using an older ESX version with a database structure, insert a row into the items table instead.

4. Quasar Inventory (QS-Inventory)

File Location: qs-inventory/config/items.lua or shared/items.lua

['weapon_glock17'] = {
['name'] = 'weapon_glock17',
['label'] = 'Glock 17',
['weight'] = 1000,
['type'] = 'weapon',
['ammotype'] = 'AMMO_PISTOL',
['image'] = 'weapon_glock17.png',
['unique'] = true,
['shouldClose'] = true,
},

5. Jaksam Inventory

File Location: jaksam_inventory/_data/items.lua

['WEAPON_GLOCK17'] = {
label = 'Glock 17',
weight = 1.0,
type = 'weapon',
ammo = 'ammo_9mm',
close = true,
},

🔧 Phase 3: Installing Attachments

Most server owners forget this step. Your weapon might shoot, but without attachments, it feels incomplete. Here is how to map components such as suppressors, scopes, and extended mags.

1. Ox Inventory

In Ox, attach the component hash to the attachment item.

['at_suppressor_light'] = {
label = 'Suppressor',
client = {
    component = {
        `COMPONENT_AT_PI_SUPP_02`,
        `COMPONENT_YOUR_CUSTOM_HASH`,
    }
}
}

2. QB-Core

QB requires mapping the specific component hash to the attachment item in qb-weapons/config.lua.

WeaponAttachments = {
['suppressor_attachment'] = {
    ['weapon_pistol'] = 'COMPONENT_AT_PI_SUPP_02',
    ['weapon_glock17'] = 'COMPONENT_YOUR_CUSTOM_HASH',
},
['flashlight_attachment'] = {
    ...
}
}

3. ESX Framework

For standard ESX, components are defined inside the weapon entry itself in config.weapons.lua.

{
name = 'WEAPON_GLOCK17',
label = _U('weapon_glock17'),
components = {
    { name = 'clip_default', label = 'Default Clip', hash = `COMPONENT_GLOCK17_CLIP_01` },
    { name = 'clip_extended', label = 'Extended Clip', hash = `COMPONENT_GLOCK17_CLIP_02` },
    { name = 'suppressor', label = 'Suppressor', hash = `COMPONENT_AT_PI_SUPP` }
}
},

4. Quasar Inventory & Jaksam

Quasar: Define the attachment as an item in items.lua with type item or attachment.

Jaksam: Edit _data/components.json and add the component hash to the corresponding category array.

"suppressor": [
"COMPONENT_AT_PI_SUPP",
"COMPONENT_YOUR_CUSTOM_HASH"
]