🔫WEAPON MENU

🔫 Weapon Menu - Complete Documentation

A comprehensive FiveM weapon customization script with real-time preview, VIP system integration, and multi-framework support.

📋 Table of Contents

  • Features

  • Installation

  • Configuration

  • Framework Support

  • VIP System

  • Modules

  • Commands

  • Multi-Player Synchronization

✨ Features

🎨 Weapon Customization

  • Weapon Tints: 8 colors for standard weapons, 32 colors for MK2 weapons

  • Patterns: 11 predefined patterns (easily extensible)

  • Custom Skins: Support for image URLs (JPG, PNG, GIF, WebP)

  • Weapon Components: Special skins for specific weapons (knives, knuckles, bats, etc.)

🎭 Animation System

  • Weapon Animations: 5+ animation styles (Default, First Person, Gangster, etc.)

  • Holster Animations: 7+ holster styles (Side, Back, Front, etc.)

  • Persistence: All animations saved and restored automatically

👁️ Preview System

  • Real-time preview before applying skins

  • Toggle preview on/off

  • Hover preview for quick viewing

  • Smart conflict management

💾 Save System

  • Client-side KVP storage

  • Per-weapon customization saving

  • Automatic restoration on spawn/restart

🛠️ Installation

Prerequisites

  • FiveM Server with lua54 enabled

  • No framework required (works standalone)

Steps

  1. Download and extract the resource to your server:

    resources/weaponmenu/

  2. Add to server.cfg:

    ensure weaponmenu

  3. Restart your server or start the resource:

    restart weaponmenu

⚙️ Configuration

All configuration is done in shared/config.lua.

Basic Settings

-- Command to open menu
Config.Command = 'weaponmenu'

-- Keymapping (F9 by default)
Config.KeyMapping = {
    enabled = true,
    key = "F9",
    description = "Open weapon menu"
}

-- Language
Config.Locale = 'en' -- 'fr', 'es', 'en'

-- Preview system
Config.Preview = {
    enabled = true
}

Camera Settings

Config.Camera = {
    viewModeOnOpen = 4,  -- 0-4 (First Person Aiming = 4)
    viewModeOnClose = 1  -- 0-4 (Third Person Medium = 1)
}

Tenor GIF Integration

Config.Tenor = {
    enabled = true,
    apiKey = "YOUR_API_KEY",  -- Get free key at https://developers.google.com/tenor/guides/quickstart
    rating = "g",             -- g, pg, pg13, r
    limit = 20,
    mediaFilter = "minimal"   -- minimal (no watermark) or basic
}

🔌 Framework Support

The script automatically detects your framework:

  • ✅ ESX Legacy - Detected if es_extended is started

  • ✅ QBCore - Detected if qb-core is started

  • ✅ Standalone - Used if no framework detected (uses playerSpawned event)

No configuration needed! The script will display a console message indicating which framework was detected.

👑 VIP System

Enable VIP System

Config.VIP = {
    enabled = true,
    checkVIP = function(source)
        -- Your VIP check logic here
        -- Example: TriggerServerEvent('weaponmenu:checkVIP')
        -- return true or false
        return false
    end
}

Make Modules VIP-Only

Config.Modules.weaponAnimation = {
    enabled = true,
    vipOnly = true  -- Only VIP players can access
}

📦 Modules

Enable or disable any module:

Config.Modules = {
    weaponTint = {
        enabled = true,
        vipOnly = false
    },
    skinLimitedEdition = {
        enabled = true,
        vipOnly = false
    },
    customSkin = {
        enabled = true,
        vipOnly = false
    },
    weaponSkin = {
        enabled = true,
        vipOnly = false
    },
    weaponAnimation = {
        enabled = true,
        vipOnly = false
    },
    holsterAnimation = {
        enabled = true,
        vipOnly = false
    }
}

Note: If you disable a module, it will be hidden from the menu automatically.

⌨️ Commands

Command
Description

/weaponmenu

Open the weapon customization menu

/resetweaponkvp

Reset all saved weapon customizations

Default Key: F9 (configurable in Config.KeyMapping)

🎯 Usage

  1. Equip a weapon in-game

  2. Open the menu with /weaponmenu or F9

  3. Browse categories:

    • Weapon Tint

    • Skin Limited Edition (Patterns)

    • Custom Skin (URL)

    • Weapon Skin (Components)

    • Weapon Animation

    • Holster Animation

  4. Preview before applying (toggle with eye icon)

  5. Apply your customization

All customizations are automatically saved and restored when you respawn or restart.

🌐 Multi-Player Synchronization

✅ Synchronized between clients

The following elements are visible to all players :

  • Weapon Tints : Weapon tints are synchronized and visible to everyone

  • Weapon Skins : Weapon skins (components) are synchronized

  • Holster Animations : Holster animations are synchronized

❌ Not synchronized (client-side only)

The following elements are only visible to you :

  • Skin Limited Edition : Patterns (textures) cannot be synchronized because they replace the weapon texture. If they were synchronized, it would replace all weapons for all clients

  • Custom Skin : Custom skins via URL cannot be synchronized for the same technical reason (global texture replacement)

  • Weapon Animations : Weapon animations are not synchronized because they are too costly server-side in terms of performance

Note : Even if some elements are not visually synchronized, they are still saved locally and automatically restored on your next connection.

📝 Adding Custom Patterns

Add patterns in shared/config.lua:

Config.Patterns = {
    { name = "Pattern 1", file = "1.webp" },
    { name = "Pattern 2", file = "2.webp" },
    -- Add your patterns here
}

Place pattern images in ui/images/pattern/ as WebP files.

🔧 Troubleshooting

Menu doesn't open

  • Make sure you have a weapon equipped

  • Check console for errors

  • Verify the resource is started: ensure weaponmenu

Skins not saving

  • Check client console for errors

  • Verify KVP storage is working

  • Try /resetweaponkvp and reapply

VIP system not working

  • Ensure Config.VIP.enabled = true

  • Check your checkVIP function returns correct values

  • Verify module has vipOnly = true

PreviousROBERRY GRAPSEEDNextID CARD

Last updated