Installation Guide

This guide covers installing ARS VVS Guns V2 on your FiveM server. This is a collaboration script. The weapon assets are made by VVS Customs. This script requires two separate purchases:

Important: This script requires two separate purchases:

Get this script (ARS VVS Guns V2): https://amirobin.tebex.io/package/7430707

Get VVSGUNV2 (Weapon Assets): https://vvscustoms.tebex.io/package/7430699

VVS Customs Discord: https://discord.gg/vvscustoms

VVSGUNV2 is required for weapons to work. Without it, weapons will not function properly.

Prerequisites

oxmysql - Database connection
ox_lib - UI and library functions
ESX Legacy or QBCore framework
Supported inventory system (ox_inventory, qb-inventory, qs-inventory, ps-inventory, or ak47_inventory)
VVSGUNV2 - Weapon asset pack by VVS Customs (required, purchase: https://vvscustoms.tebex.io/package/7430699)

Framework Installation

Choose your framework below and follow all steps in order.

For ESX Legacy Framework

Follow the complete ESX Installation Guide

ESX Installation Summary:

Database Setup - Run SQL queries for:
- Main table ars_vvsguns_v2
- Job and society account for vvsgundealer
- Job grades (Goldsmith, Shopkeeper, Manager, Owner)
- Items table (if your ESX uses SQL-based items)
Weapon Definitions - Add weapons to es_extended/config.weapons.lua:
- All 25 weapons with full component support
- Pistols: G45 Custom, G17 Custom, G17S Custom, G40 Custom, Deagle Custom, SM17 Custom, M45 Custom, FN5 Custom
- Assault Rifles: AR15C Custom, AR15T Custom, Draco Custom, ARP Custom, Bruen Custom, AK102 Custom
- SMGs: APC Custom, Thompson Custom, MP7 Custom, ARP9 Custom, P90 Custom
- Shotguns: SPAS12 Custom
- Melee: Bowie Knife Custom, Butterfly Knife Custom, Katana Dragon Custom, Karambit Custom, Tactical Axe Custom
- Attachments: Extended mags (1-3), scope, suppressor, laser, grip
- Camos: Gold camo, Diamond camo
Inventory Integration - Follow one inventory guide:
- ox_inventory Installation for ox_inventory
- qs-inventory Installation for qs-inventory
- ak47_inventory Installation for ak47_inventory
Copy Images - Copy all PNG files from INSTALL_ME/images/ to your inventory images folder
Final Configuration - Set framework and image paths in config

For QBCore Framework

Follow the complete QBCore Installation Guide

QB Installation Summary:

Database Setup - Run SQL query for main ars_vvsguns_v2 table
Job Definition - Add vvsgundealer job to qb-core/shared/jobs.lua:
- Grades: Goldsmith ($50), Shopkeeper ($75), Manager ($100), Owner ($125)
Boss Menu Location - Add boss menu coordinates to qb-management config
Items Configuration - Add all items to qb-core/shared/items.lua:
- 25 weapon items with full details
- All attachments (extended mags, scope, laser, suppressor, grip, camos)
- Crafting materials (parts, gunpowder, emptyshell, gold, diamond, etc.)
Weapons Configuration - Add weapons to qb-core/shared/weapons.lua:
- Weapon definitions for damage reasons and ammo types
- All VVS weapons categorized by type (SMG, Rifle, Pistol, Shotgun, Melee)
QB-Weapons Integration (if using qb-weapons):
- Add durability multipliers to qb-weapons/config.lua
- Configure weapon attachments mapping
Inventory Integration - Follow one inventory guide:
- Default qb-inventory requires only Steps 4-5 above
- For other inventories, follow the respective guide below
Copy Images - Copy all PNG files to inventory images folder
Final Configuration - Set framework and image paths
Society Banking - Set up your banking system for society money (see Society Banking Setup)

Inventory Setup

After completing framework setup, follow the inventory guide for your system.

ox_inventory

Follow the ox_inventory Installation Guide

Setup Steps:

Weapons - Add all 25 weapons to ox_inventory/data/weapons.lua:
- Weapon name, label, weight, durability
- Ammo type mapping (ammo-9, ammo-rifle, ammo-rifle2, ammo-shotgun)
Components - Add all attachments to ox_inventory/data/weapons.lua:
- Extended magazines (mag1, mag2, mag3)
- Attachments (scope, laser, suppressor, grip)
- Camo skins (gold camo, diamond camo)
- Component hash mappings for each weapon
Items - Add crafting materials and attachments to ox_inventory/data/items.lua:
- Weapon parts (pistol, rifle, rifle2, shotgun, SMG)
- Crafting materials (gunpowder, emptyshell, switch, weaponblack, gold, diamond)
- Attachments (extended mags, scope, laser, suppressor, grip, camos)
Images - Copy all PNG files to ox_inventory/web/images/

qb-inventory (Default QB Inventory)

No additional steps needed if using default qb-inventory. Weapons and items from QB Steps 4-5 are sufficient.

qs-inventory

Follow the qs-inventory Installation Guide

Setup Steps:

Items - Add all items to qs-inventory/shared/items.lua:
- Full item definitions with images, ammo types, weights
- 25 weapons + all attachments + crafting materials
Weapon List - Add weapons to qs-inventory/shared/weapon_list.lua:
- Weapon type definitions (SMG, Rifle, Pistol, Shotgun, Melee)
Durability Config - Add durability multipliers to qs-inventory/config/config.lua
Attachments Config - Configure weapon attachments in qs-inventory/config/config.lua
Images - Copy all PNG files to qs-inventory/html/images/

ak47_inventory

Follow the ak47_inventory Installation Guide

Setup Steps:

Shared Components - Merge component definitions into ak47 shared components file
Ammo Plugin Config - Configure ammo mappings for all weapons
Rob Plugin Config - Enable all VVS weapons for robbing
Database Items - (only if needed) Run SQL items from ESX guide
Images - Copy PNG files to ak47_inventory image directory

ps-inventory

PS-inventory follows a similar structure to QB. Use the qb-inventory items as reference and adjust to ps-inventory’s file structure in ps-inventory/shared/items.lua.

Image Installation

Copy all weapon and item images from INSTALL_ME/images/ to your inventory:

Image Files Included:

25 weapon images (WEAPON_*.png files)
Attachment images (extendedmag1-3, scope, laser, suppressor, grip, switch)
Crafting materials (partspistol, partsrifle, etc., gunpowder, emptyshell, weaponblack)
Special items (diamond, gold_bar, goldcamo, diamondcamo)

Destination Paths:

Inventory	Destination Path
ox_inventory	`ox_inventory/web/images/`
qb-inventory	`qb-inventory/html/images/`
qs-inventory	`qs-inventory/html/images/`
ps-inventory	`ps-inventory/html/images/`
ak47_inventory	Check your ak47_inventory config for image path

Base Installation

1. Download and Place Resource

Download ARS VVS Guns V2 from portal.cfx.re and place it in your resources folder:

server-data/resources/[local]/ars_vvsguns_v2/

2. Complete Framework and Inventory Setup

Follow the framework-specific guide above for ESX or QBCore, then complete your inventory integration. All steps must be completed in order.

3. Install VVSGUNV2 Weapon Pack

Purchase and install VVSGUNV2 from https://vvscustoms.tebex.io/package/7430699 following its included installation guide. This is required for weapons to work.

Without VVSGUNV2, weapons will not function.

4. Configure Framework

Open ars_vvsguns_v2/config.lua and set your framework:

Config.Framework = 'esx' -- Use 'esx' for ESX Legacy, 'qb' for QBCore

5. Configure Inventory Images

Set the inventory image path based on your inventory system:

-- For ox_inventory:
Config.Images = 'nui://ox_inventory/web/images/'

-- For qb-inventory:
Config.Images = 'nui://qb-inventory/html/images/'

-- For qs-inventory:
Config.Images = 'nui://qs-inventory/html/images/'

-- For ps-inventory:
Config.Images = 'nui://ps-inventory/html/images/'

-- For ak47_inventory:
Config.Images = 'nui://ak47_inventory/web/build/images/'  -- Check your config for exact path

6. Add to Server Config

Add the resources to your server.cfg:

ensure ox_lib
ensure oxmysql
ensure vvsgunspacks  -- Ensure VVSGUNV2 is loaded first
ensure ars_vvsguns_v2

Note: Ensure vvsgunspacks (VVSGUNV2) is loaded before ars_vvsguns_v2.

7. Database Table

Execute the SQL from INSTALL_ME/database.sql in your database. The script will automatically create and populate the ars_vvsguns_v2 table on first start.

8. Configure Your Shops

Edit ars_vvsguns_v2/shops/vvsgundealer.lua to customize shop locations, items, prices, and settings.

Default shop location: vector3(351.0538, 3394.9087, 37.6834)

Verification

Verify VVSGUNV2 is installed and loaded first
Start your server
Check console for successful database initialization message
Approach the default VVS Guns shop location
Press E to open the shop menu
Verify weapons display with correct images from VVSGUNV2 pack
Test purchasing a weapon
Test weapon functionality in-game

Updating

Stop your server
Backup your configuration files:
- ars_vvsguns_v2/config.lua
- ars_vvsguns_v2/shops/vvsgundealer.lua
Replace the resource files with the new version
Restore your configuration files
Verify VVSGUNV2 is still the latest version
Restart your server
Test all shop functions and weapons

Troubleshooting

VVSGUNV2 Weapons Not Working

Issue: Weapons don’t fire, models don’t appear, or attachments don’t work
Solutions:
- Verify VVSGUNV2 is purchased from https://vvscustoms.tebex.io/package/7430699
- Ensure VVSGUNV2 is loaded before ars_vvsguns_v2 in server.cfg
- Check that weapon definitions are added to your framework config
- Verify component hashes match between framework and inventory
- Contact VVS Customs Discord: https://discord.gg/vvscustoms for weapon pack support

Shop Not Opening

Issue: No blip or target prompt at shop location
Solutions:
- Check that framework job is properly registered in database
- Verify blip.enable = true in shop config
- Ensure coordinates are correct
- Enable debug mode in config to check for errors

Weapons Not Showing in Inventory

Issue: Weapons appear as unknown items or don’t display
Solutions:
- Verify weapon items exist in inventory data files
- Check that weapon names match exactly (case-sensitive)
- Ensure component hashes are mapped correctly
- Confirm image files are in correct folder with exact filenames
- Restart the inventory resource

Attachments Not Working

Issue: Can’t attach mags, scopes, or other components to weapons
Solutions:
- ESX: Verify component hashes in es_extended/config.weapons.lua match inventory config
- QB: Check WeaponAttachments in qb-weapons/config.lua for correct mappings
- Ensure attachment items exist in inventory
- Verify component type matches (magazine, scope, muzzle, etc.)

Society Money Not Depositing

Issue: Purchases don’t add money to shop account
Solutions:
- ESX: Ensure esx_society is running and society_vvsguns account exists
- QB: Check Config.SocietyInBank matches your banking system (see Society Banking Setup)
- For okokBanking, verify job is added to Config.Societies
- Restart framework and inventory resources

Job Grades Not Working

Issue: Players can’t access management features
Solutions:
- Verify job grades exist in database
- Check managementRankFor settings in shop config
- Ensure player has sufficient job grade
- Re-run job SQL queries and restart framework

Framework-Specific Resources

Framework	Required Guides
ESX Legacy	ESX Installation
QBCore	QBCore Installation
ox_inventory	ox_inventory Installation
qs-inventory	qs-inventory Installation
ak47_inventory	ak47_inventory Installation
Society Banking	Society Banking Setup

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.