🔪Spectro VIP Weapons

📘 Spectro VIP Weapons - Complete Documentation

Advanced VIP weapon management system for FiveM with administration panel, custom loadouts and flexible permissions

---

📋 Table of Contents

1. Key Features

2. Requirements and Dependencies

3. Step-by-Step Installation

4. General Configuration

5. Weapon Management

6. Admin Panel

7. Permission System

8. Loadout System

9. Cacheable Weapons System

10. Frequently Asked Questions

11. Troubleshooting

12. Advanced Settings

---

🌟 Key Features

✨ For Players

Feature	Description	Command/Key
Menu Access	Modern interface to manage VIP weapons	/weapons or F4
Loadout System	Save up to 10 weapon configurations	From menu
Weapon Customization	Add attachments to any allowed weapon	In weapon menu
Quick Disarm	Unequip current VIP weapon	X
Personal Settings	Configure position, notifications, etc.	In menu

🛠️ For Administrators

Feature	Description	Command/Key
Admin Panel	Complete permission management	/weaponadmin or F9
Player Management	Control permissions online/offline	Admin panel
Logging System	Records in console/file/Discord	Automatic
Console Commands	Manage from server console	addweaponadmin etc.
Cacheable Weapons	Advanced requirement system	Admin panel

🔧 Technical Features

• Multi-Framework: ESX, QBCore, vRP and Standalone

• Database: MySQL with 5 main tables

• Optimization: Low resource consumption

• Flexible Configuration: Over 50 configurable options

• Restricted Zones: Disable weapons in specific areas

---

📋 Requirements and Dependencies

🚨 Mandatory Dependencies

Dependency	Description	Status
mysql-async/oxmysql	Database system	✅ Compatible with all
MenuV	Menu system	✅ Required
MySQL/MariaDB	Database	✅ Required

⚠️ IMPORTANT: MenuV is a critical dependency. Without it, the script won't work. Included in purchase link and detailed in description: https://spectro.tebex.io/

✅ Database: The script is compatible with all FiveM database systems (mysql-async, oxmysql, ghmattimysql, etc.). No compatibility issues.

📊 Server Requirements

Requirement	Specification
FiveM Server	Latest version available
Lua	5.4 enabled
Free Space	Minimum 50MB
RAM	Minimum 100MB available

🔗 Compatible Frameworks

Framework	Version	Status	Inventories
ESX Legacy	1.8+	✅ Fully compatible	✅ All inventories
QBCore	Latest	✅ Fully compatible	✅ All inventories
vRP	1.0+	✅ Fully compatible	✅ All inventories
Standalone	-	✅ No framework required	✅ No issues

✅ Compatibility Guarantee: This script is 100% compatible with ALL existing inventories:

• Common inventories (ox_inventory, lj-inventory, qb-inventory, etc.)

• Custom and modified inventories

• Self-developed inventories

• No matter the system, it will work perfectly without problems or conflicts.

🎁 Includes sample weapons: The script comes pre-configured with 2 default GTA weapons that you can modify as you wish (ready to use).

---

🔧 Step-by-Step Installation

Step 1: Preparation

1. Download script files

2. Extract contents to a temporary directory

3. IMPORTANT: Rename main folder to Spectro_weaponvip

Step 2: Dependencies

# Use any supported database system
ensure mysql-async  # Or your preferred system (oxmysql, ghmattimysql, etc.)

# Install MenuV (included in purchase link)
ensure MenuV

Note: The script is compatible with all common FiveM database systems.

Step 3: Database

-- Execute in your MySQL manager (phpMyAdmin, HeidiSQL, etc.)
source install.sql

Tables created:

• spectro_weapon_permissions

• spectro_loadouts

• spectro_cacheable_weapons

• spectro_preferences

• spectro_user_settings

Step 4: Server.cfg Configuration

# Add in correct order
ensure your_db_system  # mysql-async, oxmysql, etc.
ensure MenuV
ensure Spectro_weaponvip

Step 5: Initial Configuration

1. Open config.lua

2. Modify admin line:

Config.Admin.Admins = {
    "license:your_license_here"  -- Replace with your license
}

1. Adjust other values as needed

Step 6: Restart Server

# In server console
refresh
restart Spectro_weaponvip

Step 7: OX_inventory adaptation (Only for users that use OX Inventory)

1. Go to the ox_inventory folder

2. Go to the modules folder which is inside the ox_inventory folder

3. Inside the modules folder, go to the folder called weapon

4. Inside the weapon folder open the client.lua

5. Inside the file, look for the following line and delete it (It is usually around line 134):

   RemoveAllPedWeapons(cache.ped, true)

---

⚙️ General Configuration

🎨 Menu Configuration

Config.Menu = {
    Colors = {
        r = 236,  -- Red (0-255)
        g = 255,  -- Green (0-255)  
        b = 71    -- Blue (0-255)
    },
    Position = "centerright",     -- Menu position
    BottomText = "VIP WEAPONS",   -- Bottom text
    Command = "weapons",          -- Open command
    Hotkey = {
        Enabled = true,           -- Enable hotkey
        Key = "F4"               -- Assigned key
    }
}

✅ Full Compatibility: No matter what framework or inventory you use, this script will work perfectly without additional modifications.

📍 Available Positions

Position	Code	Screen Location
Top Left	topleft	Upper left corner
Top Center	topcenter	Top center
Top Right	topright	Upper right corner
Center Left	centerleft	Center left
Center	center	Screen center
Center Right	centerright	Center right
Bottom Left	bottomleft	Lower left corner
Bottom Center	bottomcenter	Bottom center
Bottom Right	bottomright	Lower right corner

🚫 Disabled Zones

Config.Menu.DisabledZones = {
    {
        x = 1234.5,      -- X coordinate
        y = 6789.0,      -- Y coordinate
        z = 30.5,        -- Z coordinate
        radius = 50.0,   -- Zone radius
        message = "VIP weapons disabled here"
    },
    -- Add more zones:
    {
        x = -500.0,
        y = -300.0,
        z = 35.0,
        radius = 100.0,
        message = "Safe zone - Weapons disabled"
    }
}

---

🔫 Weapon Management

📝 Weapon System

✅ Includes sample weapons: The script already comes with 2 default GTA weapons ready to use in defaultlist.json. You can:

• Use them as they are

• Modify them according to your needs

• Add more GTA V weapons or mods

🚀 Add any weapon: In addition to included ones, you can add any GTA V weapon or custom weapon mods.

🛠️ Add New Weapons (Detailed Guide)

Step 1: Basic Structure

To add a new weapon, open addonlist.json file and add a new entry with this structure:

"WEAPON_HASH": {
    "label": "Name that will appear in menu",
    "spawnammo": 200,  // Ammo amount when spawned
    "attachments": {
        // Attachments go here
    }
}

Step 2: Complete Example - Adding AK-47

"WEAPON_ASSAULTRIFLE": {
    "label": "AK-47",
    "spawnammo": 300,
    "attachments": {
        "Magazines": [
            {
                "label": "Standard Magazine",
                "value": "COMPONENT_ASSAULTRIFLE_CLIP_01"
            },
            {
                "label": "Extended Magazine",
                "value": "COMPONENT_ASSAULTRIFLE_CLIP_02"
            }
        ],
        "Scopes": [
            {
                "label": "Holographic Sight",
                "value": "COMPONENT_AT_SCOPE_MEDIUM"
            },
            {
                "label": "Thermal Scope",
                "value": "COMPONENT_AT_SCOPE_THERMAL"
            }
        ],
        "Accessories": [
            {
                "label": "Suppressor",
                "value": "COMPONENT_AT_AR_SUPP_02"
            },
            {
                "label": "Flashlight",
                "value": "COMPONENT_AT_AR_FLSH"
            },
            {
                "label": "Grip",
                "value": "COMPONENT_AT_AR_AFGRIP"
            }
        ],
        "Skins": [
            {
                "label": "Yeti Camo",
                "value": "COMPONENT_ASSAULTRIFLE_VARMOD_LUXE"
            }
        ]
    }
}

Step 3: How to Find Weapon HASH

Weapon	Hash
Pistol	WEAPON_PISTOL
Combat Pistol	WEAPON_COMBATPISTOL
Micro SMG	WEAPON_MICROSMG
SMG	WEAPON_SMG
Assault Rifle (AK-47)	WEAPON_ASSAULTRIFLE
Carbine (M4A1)	WEAPON_CARBINERIFLE
Advanced Rifle	WEAPON_ADVANCEDRIFLE
Shotgun	WEAPON_PUMPSHOTGUN
Combat Shotgun	WEAPON_ASSAULTSHOTGUN
Sniper Rifle	WEAPON_SNIPERRIFLE
Heavy Sniper	WEAPON_HEAVYSNIPER

Step 4: How to Find Components/Attachments

1. For Base GTA V Weapons:

// Common component examples:
"COMPONENT_AT_AR_SUPP"          // Rifle suppressor
"COMPONENT_AT_AR_SUPP_02"       // Alternative suppressor
"COMPONENT_AT_AR_FLSH"          // Rifle flashlight
"COMPONENT_AT_AR_AFGRIP"        // Foregrip
"COMPONENT_AT_SCOPE_MEDIUM"     // Medium scope
"COMPONENT_AT_SCOPE_LARGE"      // Large scope
"COMPONENT_AT_PI_SUPP"          // Pistol suppressor
"COMPONENT_AT_PI_FLSH"          // Pistol flashlight

2. For Modded Weapons:

If using modded weapons (like WeaponPack, etc.), you need:

1. Open the mod's weapons.meta file

2. Search for attachBone or components

3. Copy exact component names

Step 5: Category Structure

You can organize attachments as you wish:

"attachments": {
    "Magazines": [
        // All magazines here
    ],
    "Scopes": [
        // All scopes here
    ],
    "Barrels": [
        // All barrels/suppressors here
    ],
    "Accessories": [
        // Other accessories here
    ],
    "Customization": [
        // Skins, tints, etc.
    ]
}

Step 6: Example with Modded Weapon

"WEAPON_M4A1_CUSTOM": {
    "label": "M4A1 Custom",
    "spawnammo": 150,
    "attachments": {
        "Optics": [
            {
                "label": "EOTech 553",
                "value": "COMPONENT_CUSTOM_EOTECH553"
            },
            {
                "label": "ACOG Scope",
                "value": "COMPONENT_CUSTOM_ACOG"
            }
        ],
        "Barrel": [
            {
                "label": "Long Barrel",
                "value": "COMPONENT_CUSTOM_LONGBARREL"
            },
            {
                "label": "AAC Suppressor",
                "value": "COMPONENT_CUSTOM_AAC_SUPP"
            }
        ]
    }
}

Step 7: Grant Permissions

Once weapon is added, remember to:

1. Restart script or server

2. Open admin panel (/weaponadmin)

3. Select player

4. Add the new weapon

5. Ready to use!

Step 8: Verify Hash

If unsure about weapon hash, you can:

1. Test weapon in-game

2. Open console (F8)

3. Type GetCurrentPedWeapon() while having weapon equipped

4. Number shown is the hash (convert to name using online tools)

Useful Tips:

• Unique names: Each weapon must have unique hash

• Clear names: Use descriptive labels for attachments

• Categorization: Group similar attachments in same category

• Testing: Test each weapon after adding

• Backup: Always backup file before modifying

Complete addonlist.json Example:

{
    "config" : {
        "color": {
            "r": 236,
            "g": 255,
            "b": 71
        },
        "bottomText": "VIP WEAPONS",
        "position": "centerright",
        "command": "weapons",
        "hotkey": {
            "enabled": true,
            "key": "F4"
        }
    },
    
    "WEAPON_ASSAULTRIFLE": {
        "label": "AK-47",
        "spawnammo": 300,
        "attachments": {
            // ... (as in previous example)
        }
    },
    
    "WEAPON_CARBINERIFLE": {
        "label": "M4A1",
        "spawnammo": 300,
        "attachments": {
            // ... your attachments here
        }
    }
    
    // Add more weapons following same format...
}

📋 Addable GTA V Weapons List

Category	Available Weapons
Pistols	WEAPON_PISTOL, WEAPON_PISTOL50, WEAPON_COMBATPISTOL, WEAPON_APPISTOL, WEAPON_HEAVYPISTOL, WEAPON_REVOLVER, WEAPON_MARKSMANPISTOL
SMGs	WEAPON_MICROSMG, WEAPON_SMG, WEAPON_ASSAULTSMG, WEAPON_COMBATPDW, WEAPON_MACHINEPISTOL, WEAPON_MINISMG
Assault Rifles	WEAPON_ASSAULTRIFLE, WEAPON_CARBINERIFLE, WEAPON_ADVANCEDRIFLE, WEAPON_SPECIALCARBINE, WEAPON_BULLPUPRIFLE, WEAPON_COMPACTRIFLE
Shotguns	WEAPON_PUMPSHOTGUN, WEAPON_SAWNOFFSHOTGUN, WEAPON_ASSAULTSHOTGUN, WEAPON_BULLPUPSHOTGUN, WEAPON_HEAVYSHOTGUN, WEAPON_DBSHOTGUN
Snipers	WEAPON_SNIPERRIFLE, WEAPON_HEAVYSNIPER, WEAPON_MARKSMANRIFLE
Machine Guns	WEAPON_MG, WEAPON_COMBATMG, WEAPON_GUSENBERG

---

🛡️ Admin Panel

🔑 Panel Access

Method	Command/Key	Requirements
Command	/weaponadmin	Be administrator
Hotkey	F9	Be administrator

🎯 Main Functions

1. Player Management

Option	Description	Available Actions
Online Players	List of connected players	View permissions, Add/Remove weapons
Offline Players	Players with saved permissions	View permissions, Add/Remove weapons

2. Weapon Management

Action	Description	Confirmation
Add Weapon	Grant permission for new weapon	Requires confirmation
Remove Weapon	Revoke existing permission	Requires confirmation
View Permissions	List all player weapons	-

3. Reporting System

-- Information included in reports:
- Total granted permissions
- List by player
- Grant dates
- Administrator who granted permission

4. Cacheable Weapons

Setting	Description	Values
Status	Enable/Disable caching	true/false
Base Weapon	Required weapon for VIP use	Weapon list
Save Config	Database persistence	Automatic

💻 Admin Commands

# Add administrator
addweaponadmin license:XXXXXXXXXX

# Remove administrator  
removeweaponadmin license:XXXXXXXXXX

---

🔐 Permission System

👤 License-Based Permissions

-- Individual permission query
SELECT * FROM spectro_weapon_permissions 
WHERE license = 'license:XXXXXXXXXX';

👥 Group-Based Permissions

Config.Permissions = {
    UseGroupSystem = true,      -- Enable group system
    Framework = "esx",          -- Framework to use
    
    FullAccessGroups = {        -- Groups with full access
        "admin",
        "superadmin",
        "vip"
    },
    
    GroupWeaponPermissions = {  -- Specific permissions
        ["moderator"] = {
            "WEAPON_PISTOL",
            "WEAPON_CARBINERIFLE"
        },
        ["vip"] = {
            "WEAPON_PISTOL",
            "WEAPON_CARBINERIFLE",
            "WEAPON_SNIPERRIFLE"
        }
    }
}

🔍 Supported Identifiers

Type	Format	Example
License	license:	license:abc123...
Steam	steam:	steam:11000001234567890
Discord	discord:	discord:123456789012345678
IP	ip:	ip:192.168.1.1

---

💾 Loadout System

📋 Create Loadouts

1. Equip weapons you want to save

2. Add attachments to each weapon

3. Open menu (/weapons or F4)

4. Select "Manage Loadouts"

5. Choose "Create new loadout"

6. Enter custom name

7. Confirm to save

⚙️ Loadout Configuration

Config.Loadouts = {
    MaxLoadoutsPerPlayer = 10,    -- Per-player limit (0 = no limit)
    AllowCustomNames = true,      -- Allow custom names
    SaveCooldown = 5,            -- Seconds between saves (0 = no cooldown)
    OnlyVIPWeapons = true,       -- Save only VIP weapons
    DefaultNameFormat = "Loadout_%s"  -- Default name format
}

📊 Data Structure

Field	Type	Description
license	VARCHAR(255)	Player license
name	VARCHAR(255)	Loadout name
weapons	TEXT	Weapons JSON
components	LONGTEXT	Attachments JSON

🎯 Advanced Features

• Save cooldown: Prevents spam

• Maximum limit: Storage control

• Attachment saving: Complete configuration

• Quick loading: Immediate application

---

🔒 Cacheable Weapons System

💡 Concept

Cacheable weapons require players to own a "base weapon" to use the VIP weapon.

Example: To use WEAPON_SCAR17FM, player must have WEAPON_PISTOL.

⚡ How It Works

// Workflow:
1. Player gets VIP weapon
2. System checks every 2 seconds
3. If no base weapon → remove VIP weapon
4. Show notification to player

🛠️ Global Configuration

Config.CacheableWeapons = {
    Enabled = true,              -- Enable system
    CheckInterval = 2000,        -- Check interval (ms)
    DefaultConfig = {
        Enabled = false,         -- Default state
        RequiredWeapon = "WEAPON_PISTOL"  -- Default base weapon
    }
}

📑 Per-Weapon Configuration

VIP Weapon	Required Base Weapon	Status
WEAPON_SCAR17FM	WEAPON_PISTOL	⚪ Configurable
WEAPON_M6IC	WEAPON_SNSPISTOL	⚪ Configurable
WEAPON_MICROSMG	WEAPON_PISTOL	⚪ Configurable

💾 Persistence

• Configuration saved in spectro_cacheable_weapons

• Real-time updates

• Automatic client synchronization

---

❓ Frequently Asked Questions

🔧 Installation and Configuration

❓ Why won't my menu open?

Possible causes and solutions:

1. Missing dependencies

   # Check in console:
   ensure your_db_system  # Any database system
   ensure MenuV

2. Incorrect resource name

   • Must be exactly: Spectro_weaponvip

   • Check case sensitivity

3. Insufficient permissions

   SELECT * FROM spectro_weapon_permissions WHERE license = 'your_license';

4. Key conflicts

   • Change key in config.lua

   • Try command /weapons

❓ How do I add new weapons?

Detailed step-by-step:

1. Get weapon hash

   -- Example for AK-47:
   "WEAPON_ASSAULTRIFLE"

2. Create structure in addonlist.json

   "WEAPON_ASSAULTRIFLE": {
       "label": "AK-47",
       "spawnammo": 300,
       "attachments": {}
   }

3. Add attachments (optional)

   "attachments": {
       "Scopes": [
           {
               "label": "Holographic Sight",
               "value": "COMPONENT_AT_SCOPE_MACRO"
           }
       ]
   }

4. Grant permissions via admin panel

❓ What is MenuV and where do I get it?

Complete information:

• What is it?: Menu system for FiveM

• Is it free?: No, included with script purchase

• Is it required?: Yes, script won't work without MenuV

• Installation: File and link included with purchase

🎮 Script Usage

❓ Do loadouts save on restart?

Yes, completely:

• Saved in MySQL database

• Persist between server restarts

• Include all weapons and attachments

• No time limit

❓ Can I use this script without framework?

Yes, standalone mode:

Config.Framework.Type = "standalone"

Available features:

• ✅ License-based permission system

• ✅ Complete loadouts

• ✅ Admin panel

• ❌ Group/job permissions

❓ Are weapons permanent?

Persistence options:

1. By default: Temporary weapons

   • Lost on death/reconnect

2. With persistence enabled:

   Config.Advanced.PersistentWeapons = true

   • Maintained on death/reconnect

🛡️ Administration

❓ How do I add more administrators?

Available methods:

1. Via command (in console):

   addweaponadmin license:XXXXXXXXXX

2. In config.lua:

   Config.Admin.Admins = {
       "license:admin1",
       "license:admin2"
   }

3. Direct database:

   UPDATE adminconfig.json

❓ How does the logging system work?

Available options:

1. Server console:

   Config.Admin.Logs.Type = "console"

2. Text file:

   Config.Admin.Logs.Type = "file"
   Config.Admin.Logs.Filename = "weapons.log"

3. Discord webhook:

   Config.Admin.Logs.Type = "discord"
   Config.Admin.Logs.Webhook = "your_webhook_here"

🔄 Integration

❓ Is it compatible with other weapon scripts?

General compatibility:

• ✅ All inventories: ox_inventory, lj-inventory, qb-inventory, cheeza-inventory, esx_addoninventory, etc.

• ✅ Custom inventories: Your own developed inventory

• ✅ Modified inventories: Any customized version

• ✅ Crafting scripts

• ✅ Ammo scripts

• ⚠️ May require adjustments with other weapon menus

Recommended configuration:

Config.Advanced.UseCustomInventory = true
Config.Advanced.AddToInventoryEvent = "your_event_here"

❓ Does it work with all ESX/QBCore versions?

Guaranteed compatibility:

Framework	Compatible Inventories	Status
ESX Legacy	ox_inventory, esx_addoninventory, codem-inventory	✅ 100%
ESX Final	All ESX inventories	✅ 100%
QBCore	qb-inventory, ox_inventory, lj-inventory, ps-inventory	✅ 100%
vRP	All vRP inventories	✅ 100%
Custom	Your own or modified inventory	✅ 100%

🔥 No additional configuration: Script automatically detects your inventory and framework, working perfectly from first run.

🎁 Bonus: Includes 2 GTA weapons already configured that you can modify as needed.

🔧 Troubleshooting

❓ Error: "attempt to index a nil value (field 'Config')"

Causes and solutions:

1. Config.lua not loaded:

   -- Check in server.cfg:
   shared_script 'config.lua'

2. Syntax error in config.lua:

   • Check commas and brackets

   • Validate with JSON editor

3. Incorrect load order:

   # server.cfg (correct order):
   ensure your_db_system  # Your database system
   ensure MenuV
   ensure Spectro_weaponvip

❓ Cacheable weapons not working

Step-by-step diagnosis:

1. Verify it's enabled:

   Config.CacheableWeapons.Enabled = true

2. Check per-weapon configuration:

   SELECT * FROM spectro_cacheable_weapons;

3. Debug in console:

   Config.Advanced.Debug = true

4. Verify intervals:

   Config.CacheableWeapons.CheckInterval = 2000

---

🚀 Advanced Settings

🔧 Performance Settings

Config.Advanced = {
    Debug = false,                        -- Enable detailed logs
    SaveUserPreferences = true,           -- Save user preferences
    UseCustomInventory = false,           -- Auto inventory detection
    AddToInventoryEvent = "auto",         -- Automatic detection
    PersistentWeapons = false,           -- Permanent weapons
    SaveWeaponsOnDisconnect = "spectro:savePlayerWeapons",
    LoadWeaponsOnConnect = "spectro:loadPlayerWeapons"
}

💡 Auto-detection: Script automatically detects your inventory and framework. UseCustomInventory option can be left as false for automatic operation.

🌐 Localization

Config.Locales = {
    ['en'] = {
        ['weapons_title'] = 'My VIP Weapons',
        ['loadouts_title'] = 'My Loadouts',
        // ...more translations
    },
    ['es'] = {
        ['weapons_title'] = 'Mis Armas VIP',
        ['loadouts_title'] = 'Mis Loadouts',
        // ...more translations
    }
}

Config.DefaultLocale = 'en'  -- Default language

📊 Database - Complete Structure

Table	Purpose	Main Fields
spectro_weapon_permissions	Individual permissions	license, weapon_hash, granted_by
spectro_loadouts	Saved configurations	license, name, weapons, components
spectro_cacheable_weapons	Cacheable weapon config	weapon_hash, enabled, required_weapon
spectro_preferences	User preferences	license, open_loadouts
spectro_user_settings	Custom settings	license, settings

🔐 Security and Permissions

-- Multiple identifier verification
Config.Permissions.CheckIdentifiers = {
    "license",
    "steam",
    "discord",
    "ip"
}

-- ACE permission level
Config.Admin.CommandPermissionLevel = "admin"

---

📞 Support and Contact

📋 Required Support Information

When contacting support, always include:

1. Script version: v1.0

2. Framework used: ESX/QBCore/vRP/Standalone

3. Server logs:

   # Last 50 server linestail -n 50 server.log

4. Detailed problem description

5. Steps to reproduce the error

🔍 Self-Diagnosis

-- Enable debug mode:
Config.Advanced.Debug = true

-- Verify dependencies:
ensure your_db_system  # Any database system
ensure MenuV

-- Check database:
SHOW TABLES LIKE 'spectro_%';

---

📄 Final Notes

🔄 Updates

• Updates delivered through purchase channel

• Changelog included with each update

• Guaranteed backward compatibility

📋 License

This script is protected by copyright. Commercial use or redistribution is prohibited according to purchase license terms.

---

Documentation updated for Spectro VIP Weapons v1.0 - Last update: 2025