Administrator Guide

This guide covers managing ARS VVS Guns V2 as a server administrator. It includes shop setup, stock control, price management, and troubleshooting.

Initial Setup
Adding New Shops
Stock Control
Price Management
Crafting Configuration
Commands Reference
Troubleshooting

1. Initial Setup

Job Grades Reference

The vvsgundealer job uses the following grade structure:

Grade	Name	Salary (QB)	Salary (ESX)	Role
0	Goldsmith	$50	$20	Entry-level employee
1	Shopkeeper	$75	$40	Regular employee
2	Manager	$100	$60	Can manage stock and prices
3	Owner	$125	$100	Boss access, full control

Verify VVSGUNV2 Installation

Before using ARS VVS Guns V2, ensure VVSGUNV2 is properly installed:

Purchase VVSGUNV2 from https://vvscustoms.tebex.io/package/7430699
Install the weapon pack following its included guide
Ensure ensure vvsgunspacks appears before ensure ars_vvsguns_v2 in server.cfg
Verify weapon models appear in-game
Test weapon functionality

Without VVSGUNV2, weapons will not work. Contact VVS Customs Discord: https://discord.gg/vvscustoms

Configure Framework

Edit config.lua:

Config.Framework = 'esx'  -- 'esx' for ESX Legacy, 'qb' for QBCore
Config.Images = 'nui://ox_inventory/web/images/'  -- Match your inventory

Database Setup

The script automatically creates the ars_vvsguns_v2 table on first start. Optionally, you can run INSTALL_ME/database.sql manually.

2. Adding New Shops

Create Shop Configuration

Open shops/vvsgundealer.lua and add a new entry to Config.Shop:

Config.Shop['newshop'] = {
    -- Map blip configuration
    blip = {
        enable = true,
        name = 'New Gun Shop',
        sprite = 617,
        color = 3,
        size = 0.8,
        radius = 0.0,
        radius_color = 4
    },

    -- Shop description shown to players
    description = 'Welcome to our gun shop!',

    -- Shop logo image path
    logo = 'images/shoplogo.png',

    -- Boss menu location (for employee management)
    boss_action = vector3(x, y, z),

    -- Management menu location (for stock/price control)
    management = vector3(x, y, z),

    -- Minimum grade required for management tasks
    managementRankFor = {
        price = 2,   -- Grade required to change prices
        stock = 2,   -- Grade required to manage stock
    },

    -- Auto-restocking configuration
    autoStock = {
        enable = true,      -- Enable/disable auto restock
        slots = 10,         -- Max stock per item
        regeneration = 10,  -- Minutes between restocks
        add = 10            -- Items to add per restock
    },

    -- Crafting system configuration
    crafting = {
        menu = vector3(x, y, z),  -- Crafting menu location
        data = {
            WEAPON_EXAMPLE = {
                reward = 1,  -- Amount of weapon to create
                required = {
                    { item = 'partspistol', quantity = 1, willremove = true }
                },
                steps = {
                    { pos = vector4(x, y, z, h), delay = 10, msg = 'Step 1: Gathering materials...' },
                    { pos = vector4(x, y, z, h), delay = 10, msg = 'Step 2: Assembling...' },
                    { pos = vector4(x, y, z, h), delay = 10, msg = 'Step 3: Finalizing...' },
                }
            },
        },
    },

    -- Storage system for purchasing materials
    storage = {
        enable = true,
        pos = vector4(x, y, z, h),
        items = {
            partspistol = {
                name = 'Weapon Parts Pistol',
                price = 500,         -- Cost to purchase from society funds
                slots = 50,          -- Max stock capacity
                available = 50,      -- Initial stock
                regeneration = 60,    -- Seconds to regenerate 1 item
                timeleft = 10        -- Internal timer (do not edit)
            },
        },
    },

    -- Shop entrance coordinates (where players buy weapons)
    sell_coords = {
        vector3(x, y, z),
    },

    -- Employee stash configuration
    stash = {
        enable = true,
        pos = vector4(x, y, z, h),
        prop = nil,  -- Optional: prop model for stash
        minGrade = 0,
        slots = 50,
        maxWeight = 100000,
    },

    -- Market items and shop pages
    data = {
        market_items = {
            WEAPON_EXAMPLE = {
                name = "Example Weapon",
                page = 0,
                process = true,
            },
        },
        pagination = {
            [0] = { name = "Pistols", icon = 'fa-gun' },
            [1] = { name = "Rifles", icon = 'fa-gun' },
            [2] = { name = "Shotguns", icon = 'fa-gun' },
        },
    }
}

Shop Items Automatically Managed

Items added to market_items automatically appear in database
Items removed from config automatically removed from database
No manual SQL editing required

3. Stock Control

Refill All Items in Shop

Use the admin command to add stock to all items:

/vvsgundealerrefill vvsgundealer 10

This adds 10 stock to every item in the vvsgundealer shop.

Refill Specific Item

Add stock to a single item:

/vvsgundealerrefillitem vvsgundealer WEAPON_G45VVR 20

This adds 20 stock to the G45 Custom weapon only.

Auto-Stock Configuration

Enable automatic restocking in the shop config:

autoStock = {
    enable = true,      -- Turn on auto restock
    slots = 10,        -- Maximum stock per item
    regeneration = 10,  -- Check every 10 minutes
    add = 10            -- Add 10 items per restock
}

The auto-stock system runs every 10 minutes and adds configured items until reaching slots limit.

Storage Regeneration

Storage items (crafting materials) regenerate automatically:

partspistol = {
    slots = 50,          -- Maximum capacity
    available = 50,      -- Current stock
    regeneration = 60,   -- Regenerate 1 item every 60 seconds
    timeleft = 10        -- Time until next regeneration (auto-managed)
}

4. Price Management

Set All Item Prices

Change prices for all items in a shop:

/vvsgundealersetprice vvsgundealer 50000

This sets all weapons in vvsgundealer to $50,000.

Set Individual Item Price

Change price for a specific weapon:

/vvsgundealersetpriceitem vvsgundealer WEAPON_G45VVR 75000

This sets the G45 Custom weapon to $75,000.

Price Range Limits

Configure allowed price ranges in config.lua:

Config.Pricerange = {
    min = 1,
    max = 999999999,
}

Management UI enforces these limits when employees change prices.

5. Crafting Configuration

Add Craftable Weapon

Each craftable weapon requires:

WEAPON_G45VVR = {
    reward = 1,  -- Output quantity
    required = {
        { item = 'partspistol', quantity = 1, willremove = true }
    },
    steps = {
        -- Multiple stations with progress bars
        { pos = vector4(x, y, z, h), delay = 10, msg = 'Gathering raw materials...' },
        { pos = vector4(x, y, z, h), delay = 10, msg = 'Machining upper receiver...' },
        { pos = vector4(x, y, z, h), delay = 10, msg = 'Installing internal components...' },
        { pos = vector4(x, y, z, h), delay = 10, msg = 'Final assembly and inspection...' },
    }
}

Crafting Steps

pos - Vector4 position (x, y, z, heading) for each station
delay - Seconds to complete the step (with progress bar)
msg - Message displayed to player during step

Skill Check

Enable skill check mini-game after crafting:

Config.ShowSkillCheckUI = true

Config.SkillCheckMiniGame = function()
    return lib.skillCheck({ 'easy', 'easy', 'easy' }, { 'a', 's', 'd' })
end

6. Commands Reference

Command	Description	Parameters	Permission
`/vvsgundealerrefill`	Refill all items in shop	`<shop> <amount>`	group.admin
`/vvsgundealersetprice`	Set price for all items	`<shop> <price>`	group.admin
`/vvsgundealerrefillitem`	Refill specific item	`<shop> <item> <amount>`	group.admin
`/vvsgundealersetpriceitem`	Set specific item price	`<shop> <item> <price>`	group.admin

7. Troubleshooting

VVSGUNV2 Weapons Not Working

Issue: Weapons don’t fire, models don’t appear, or attachments don’t work
Solution: Verify VVSGUNV2 is purchased from https://vvscustoms.tebex.io/package/7430699 and installed correctly. Ensure VVSGUNV2 is loaded before ars_vvsguns_v2 in server.cfg. Check that weapon definitions are added to your framework config (es_extended/config.weapons.lua for ESX, qb-core/shared/weapons.lua for QB). Verify component hashes match exactly between framework and inventory configuration. Contact VVS Customs Discord: https://discord.gg/vvscustoms for weapon pack support.

Shop Not Appearing

Issue: No blip or target prompt at shop location
Solution: Verify job is properly registered in database. For ESX, re-run job SQL and restart es_extended. For QB, check job definition in qb-core/shared/jobs.lua. Check blip.enable = true in shop config. Verify coordinates are correct. Enable debug mode in config to check for errors.

Weapons Not Showing in Inventory

Issue: Weapons appear as unknown items, don’t display, or show wrong images
Solution:
- Verify weapon items exist in inventory data files (items.lua for ox/qs/ak47, or qb-core/shared/items.lua for QB)
- Check that weapon names match exactly (case-sensitive, uppercase for most systems)
- Ensure component hashes are mapped correctly between framework and inventory
- Confirm image files are copied to correct folder with exact filenames
- Restart the inventory resource or server
- For ESX: Check both es_extended/config.weapons.lua AND inventory items table
- For QB: Verify items in qb-core/shared/items.lua AND weapons in qb-core/shared/weapons.lua

Attachments Not Working

Issue: Can’t attach magazines, scopes, suppressors, or other components to weapons
Solution:
- ESX: Verify component hashes in es_extended/config.weapons.lua match your inventory attachment config
- QB with qb-weapons: Check WeaponAttachments in qb-weapons/config.lua for correct mappings
- QB without qb-weapons: Ensure attachment items exist in inventory and are properly configured
- Verify attachment type matches (magazine, scope, muzzle, flashlight, grip, skin)
- Check that component name in attachment matches the weapon component hash

Stock Not Updating

Issue: Stock changes not saving to database or not appearing in-game
Solution: Verify oxmysql is running. Check that ars_vvsguns_v2 table exists in database. Check console for SQL errors. Ensure table has correct structure (job, stock columns).

Society Money Not Depositing

Issue: Purchases don’t add money to shop account
Solution:
- ESX: Ensure esx_society is running. Verify society_vvsguns account exists in addon_account table. Restart esx_society.
- QB with qb-management: Set Config.SocietyInBank = false and ensure qb-management is running.
- QB with qb-banking: Set Config.SocietyInBank = true and ensure the vvsgundealer society account exists in qb-banking.
- QB with okokBanking: Add ["vvsgundealer"] = {3} to Config.Societies in okokBanking config. No need to change Config.SocietyInBank - okokBanking is auto-detected.
- QB with ars_banking: No additional config needed - ars_banking is auto-detected when running.
- See the Society Banking Setup guide for full details.

Job Grades Not Working

Issue: Players can’t access management features or boss menu
Solution: Verify job grades exist in database. Check managementRankFor settings in shop config match available grades. Ensure player has sufficient job grade. Re-run job SQL queries if needed. Restart framework.

Crafting Not Working

Issue: Players can’t craft weapons or crafting stations don’t appear
Solution: Verify player has required materials in inventory. Check that player has correct job and sufficient grade. Verify crafting coordinates in shop config. Check that crafting data exists for the weapon. Ensure VVSGUNV2 weapons are properly defined in your framework.

Auto-Stock Not Triggering

Issue: Items not restocking automatically despite configuration
Solution: Verify autoStock.enable = true in shop config. System checks every 10 minutes. Ensure shop name matches database entries. Check that slots, regeneration, and add values are properly set.

Database Errors

Issue: SQL errors or table creation failures
Solution: Verify database collation matches (armscii8_bin). Run SQL queries manually from INSTALL_ME folder. Check for conflicts with existing tables. Ensure oxmysql is properly configured.

Image Path Issues

Issue: Item images not loading or showing broken icons
Solution: Confirm Config.Images path points to correct inventory location. Verify image files exist in destination folder. Check file extensions match Config.ImagesFileExtension (.png). Restart inventory resource.

Need Help?

Check console for error messages
Verify database table ars_vvsguns_v2 exists
Confirm Config.Framework matches your server framework (esx or qb)
Ensure VVSGUNV2 is purchased and installed correctly from https://vvscustoms.tebex.io/package/7430699
Complete framework-specific setup from installation guide
Verify weapon and item definitions in your inventory system
Contact VVS Customs Discord for weapon pack support: https://discord.gg/vvscustoms
Refer to the framework-specific installation guides in the documentation for detailed troubleshooting

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.