Gamzky Scripts
Home Browse Scripts Free Scripts Documentation Server Name Generator Hash Resolver Discord
Login with FiveM
Basket
ESX • QBCore • Qbox compatible
Instant download
Updates included
Discord support
Secure checkout

Interactive Weapon Customizer

Resource folder: gs_weaponcustomizer

View product

Installation Instructions for Interactive Weapon Customizer

Follow these steps to install and configure gs_weaponcustomizer on your FiveM server.

  1. Download the Resource
    • Go to portal.cfx.re
    • Navigate to Assets > Granted Assets > gs_weaponcustomizer
    • Download the resource
  2. Extract the Files
    • Open the downloaded .zip file
    • Inside, you'll find a folder named gs_weaponcustomizer
    • Move the entire gs_weaponcustomizer folder into your desired server resources folder (e.g., /resources/[scripts])
  3. Add to Server Configuration
    • Open your server.cfg
    • Add the following line: 
      ensure gs_weaponcustomizer
  4. Restart the Server
    • Restart your FiveM server (Important!)
  5. Configure the Script (Optional)
    • Navigate to gs_weaponcustomizer/config.lua
    • Edit the configuration options to fit your server's needs

Additional documentation

Setting up the script

Standalone

If you are using a standalone server, so no framework/inventory system, then the script should work out of the box.

OX-Inventory

If you use ox-inventory, the script will automatically select the correct configuration files. The items related to each component is defined in config/items/ox.lua and is configured for the default ox-inventory items (located in ox_inventory/data/weapons.lua). So you do not need to do anything, it should work out of the box. Be sure to set Config.DisableAllItemRequirements = false if you want to use the component items.

ESX

If you use esx, the script will automatically select the correct configuration files. The component-names from esx (located in es_extended/shared/config/weapons.lua) are related to the actual components in config/items/esx.lua. For the weapon_carbinerifle_mk2, there is a mistake in the component definition in es_extended. To fix this, go to the es_extended/shared/config/weapons.lua file and replace the following line (769):

{ name = "scope_medium", label = TranslateCap("component_scope_medium"), hash = `COMPONENT_AT_SCOPE_MACRO_MK2` },

with this

{ name = "scope_small", label = TranslateCap("component_scope_medium"), hash = `COMPONENT_AT_SCOPE_MACRO_MK2` },

Make sure you spawn weapons through esx (like /giveweapon) if you want to save the component data. Changing components to weapons not registered to esx will cause the components not to be saved.

QB-Core

If you use qb-core, the script will automatically select the correct configuration files. The component-names from qb-core (located in qb-weapons/config.lua) are related to the actual components in config/items/qb.lua. To make qb-weapons compatible with gs_weaponcustomizer, make the following changes (otherwise the attachments won't be saved and items won't be added/removed):

Go to qb-weapons/server/main.lua, and replace line 296:

local function EquipWeaponAttachment(src, item)

with this:

function EquipWeaponAttachment(src, item)

Then, all the way at the bottom, add the following:

exports('EquipWeaponAttachment', EquipWeaponAttachment)

Be sure to set Config.DisableAllItemRequirements = false if you want to use the component items.

Origen-Inventory

If you use Origen-Inventory, the script will automatically select the correct configuration files. The component-names from origen-inventory (located in origen_inventory/config/weaponoptions.lua) are related to the actual components in config/items/qb.lua. Origen-Inventory uses the same item names as qb-core, hence they use the same file.

Other inventory systems

In this case, you will have to add the logic for the respective inventory system, to add/remove the component items and to actually save the components on the weapon. This will most likely be needed in:

  • cl_bridge.lua --> Functions.GetAvailableComponents
  • sv_bridge.lua --> Functions.AddComponent
  • sv_bridge.lua --> Functions.RemoveComponent

Lastly, you will need to replace the items in either esx.lua/ox.lua/qb.lua to the used items from your inventory system (also set Config.UsedComponentSystem correctly). If you are unsure how to add/remove components in the respective inventory system, you should consult support for that specific inventory system with the corresponding author.

Is this item-based or weapon-wheel only?

It is item-based when inventory integration is enabled. Players need component items in inventory unless you disable item requirements. The script opens a 3D overlay while holding a weapon. It does not replace the GTA weapon wheel.

  • Config.DisableAllItemRequirements = false means items are required.
  • Config.DisableAllItemRequirements = true lets players equip components without items (useful for addon weapons not registered in inventory).

Can it run standalone without QB, ESX, or a specific inventory?

Yes. There are no hard framework dependencies. Addon weapons and attachments are added through config. Saving components only works when a supported inventory is wired up.

Which inventories are supported out of the box?

  • ox_inventory
  • qb-inventory (through qb-weapons exports)
  • ESX default inventory
  • origen-inventory

core_inventory, codem-inventory, chezza, Mythic/NP Base, and qs-inventory need bridge edits. Custom vRP-style inventories need custom bridge code too.

QB attachments show in the menu but disappear when I holster the weapon

qb-inventory alone does not persist weapon components. You need qb-weapons set up correctly:

  1. Add the export from the readme to the bottom of qb-weapons/server/main.lua.
  2. Update qb-weapons to a recent version.
  3. If still broken, replace the weapon customizer server bridge and qb-weapons main file with the latest support versions.

ox_inventory errors or addon weapon attachments never save

Set up the addon weapon in ox_inventory first. Spawn component items and attach through ox_inventory alone before adding the weapon to the customizer.

Also verify weapon hash and component names match across ox_inventory weapons.lua, components.lua, and the customizer config. Metadata should use the key attachments. Turn on Config.EnableErrorMessages = true for clearer console output.

qs-inventory attachments do not stay on the weapon

Add qs-inventory handling in the server bridge similar to the ox and QB branches. Check resource state and call the correct qs export to save components.

How do I add a custom or addon weapon?

Typical ox_inventory flow:

  1. Add the weapon to ox_inventory data/weapons.lua with components.
  2. Add the weapon definition to the customizer config/weapons.lua.
  3. Add component entries to config/components.lua in the Components list.
  4. Add component items to inventory if item requirements are enabled.

My addon weapon shows a circle or attachments do nothing

components.lua has two lists: Components and Camos at the bottom. Custom components must go in Components, not after the Camos section.

Also set defaultGroupComponent = true on only one default part per group (for example CLIP_01), not on every clip variant.

Tebex-locked addon gun: can I attach parts without ox items?

Yes, if you disable item requirements for that weapon. Attachments apply visually but will not save unless ox_inventory knows the component names. You still need the component name strings from the weapon pack.

All attachment options show even though items are required

Missing component item definitions in inventory config cause the menu to stop filtering. Add the items to items/ox.lua or your QB shared items so the bridge can check ownership.

The overlay shakes or jitters when I press G

Lower Config.OverlayUpdateInterval in config. Default is 50 ms. Try 10 ms for smoother tracking.

The menu does not open after joining but works after restarting the resource

Usually a job resolution issue on connect. Update Functions.GetPlayerJob in the client bridge so it returns the correct job as soon as the player loads in.

Camo options appear but nothing applies

Camos only work on MK2 weapons (GTA limitation). Test with something like weapon_carbinerifle_mk2, not the standard carbine.

Does this support weapon tints?

No. Only camos are supported. Tints are a different GTA system and are not handled by this script.

How do I restrict customization to certain jobs?

Per weapon: set RequiredJobs in config/weapons.lua.

Globally: customize Functions.CanInteract in the client bridge. ACE, VIP, or license checks go in Functions.CanPedCustomizeWeapon.

Attachments flood inventory when I swap parts with item requirements off

If you do not want removed parts returned as items, edit the server bridge and remove or comment the line that adds the item back on component removal.

Components vanish when I leave the menu

Make sure Config.DisableAllItemRequirements = false and inventory integration is working. Components only persist when saved through the inventory bridge.

Anticheat flags the customization camera

The script creates a camera close to the player for the 3D UI. Anti-freecam or anti-invisibility systems may flag it. Adjust camera-distance thresholds in your anticheat config.

Cross-weapon attachments (shared suppressor on multiple guns)

That depends on GTA weapon meta files (weapons.meta, weaponcomponents.meta), not this script alone. The customizer can only apply components the game recognizes for that weapon hash.

Can I remove camos or change menu colors?

Yes. Remove camo entries from config to hide the paint system. UI styling is accessible in the resource files if you want a custom theme.