GFX Attachment

A weapon attachment customization script for FiveM that allows players to equip and remove weapon attachments (clips, scopes, grips, flashlights, suppressors) through an interactive workbench UI with a 3D weapon preview.

Info

Dependencies

Installation

1. Add the resource files

Copy the gfx-attachment folder into your server's resources directory.

2. Import the SQL file (ESX only)

If you are using ESX, import attachment.sql into your database. This creates the gfx_attachments table used to persist attachment data.

CREATE TABLE IF NOT EXISTS `gfx_attachments` (
  `identifier` varchar(255) DEFAULT NULL,
  `weaponName` varchar(255) DEFAULT NULL,
  `attachmentData` longtext DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;

3. Add items to your inventory

Ensure the attachment items exist in your inventory/item system. Default item names used in config:

• clip_attachment
• extendedclip_attachment
• drum_attachment
• flashlight_attachment
• grip_attachment
• scope_attachment
• suppressor_attachment

4. Place workbench props in your map

The script uses gr_prop_gr_bench_04b as the default interaction model. Place this prop in your world or add custom models to Config.OpenModels.

5. server.cfg

ensure gfx-attachment

Configuration

General

Target (qb-target integration)

DrawText (3D text interaction)

Camera Options

Attachments

Each attachment entry has the following structure:

Example attachment config entry:

["weapon_assaultrifle"] = {
    ["clip"] = {
        ["default_clip"] = {
            component = "COMPONENT_ASSAULTRIFLE_CLIP_01",
            label = "Default Clip",
            item = "clip_attachment",
        },
        ["extended_clip"] = {
            component = "COMPONENT_ASSAULTRIFLE_CLIP_02",
            label = "Extended Clip",
            item = "extendedclip_attachment",
        },
    },
    ["silencer"] = {
        ["silencer"] = {
            component = "COMPONENT_AT_AR_SUPP_02",
            label = "Suppressor",
            item = "suppressor_attachment",
        },
    },
}

Weapon Details (ESX only)

Types

Locales

Exports

No exports are created by this script.

Events

gfx-attachment:client:open

Side: Client

Opens the weapon attachment UI for the player. This event is triggered internally when the player interacts with a workbench (via DrawText or qb-target), but can also be triggered from other scripts to open the attachment menu programmatically.

-- Open the attachment UI from another client script
TriggerEvent("gfx-attachment:client:open")

gfx-attachment:server:saveWeapon

Side: Server

Saves or removes a weapon attachment for a player. Handles both equipping (removes the attachment item from inventory and saves it to the weapon) and unequipping (returns the item to inventory and removes from weapon data).

-- Equip an attachment from a server script
TriggerServerEvent("gfx-attachment:server:saveWeapon", "equip", "weapon_assaultrifle", "silencer", "silencer", 1)

-- Unequip an attachment from a server script
TriggerServerEvent("gfx-attachment:server:saveWeapon", "unequip", "weapon_assaultrifle", "clip", "extended_clip", 1)

Commands

Features

• Interactive weapon workbench with NUI-based user interface
• 3D weapon preview with rotatable camera (rotate weapon left/right/up/down from UI)
• Visual bone-point indicators showing attachment slots on the weapon model
• Supports multiple interaction methods: 3D DrawText prompt or qb-target
• Equip and unequip attachments with inventory item requirements
• Attachment categories: clips/magazines, scopes, grips, flashlights, suppressors
• Persistent attachment storage -- QBCore uses weapon item metadata, ESX uses a MySQL database table
• Automatic attachment re-application on weapon equip (ESX/standalone)
• Multi-framework support with automatic framework and inventory detection
• Compatible with multiple inventory systems (qb-inventory, ox_inventory, qs-inventory, ps-inventory, codem-inventory, gfx-inventory, esx_inventoryhud)
• Fully configurable weapon and attachment definitions per weapon type
• Escrow-protected with open config for customization

Troubleshooting