# WEAPON MENU

<figure><img src="/files/KxX9uPllaL2VMPs9lzLM" alt=""><figcaption></figcaption></figure>

## 🔫 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**:

   ```cfg
   ensure weaponmenu
   ```
3. **Restart** your server or start the resource:

   ```
   restart weaponmenu
   ```

***

### ⚙️ Configuration

All configuration is done in `shared/config.lua`.

#### Basic Settings

```lua
-- 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

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

#### Tenor GIF Integration

```lua
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
}
```

<figure><img src="/files/AHG3ICb8XvLYKWXvBfRm" alt=""><figcaption></figcaption></figure>

***

### 🔌 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

```lua
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

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

***

### 📦 Modules

Enable or disable any module:

```lua
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`:

```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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rex-studio.gitbook.io/rex-studio-docs/fivem-script/weapon-menu.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.